sneakoscope 10.2.0 → 10.3.1

package/dist/core/decisions/config.js

@@ -0,0 +1,109 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { nowIso, readJson, writeJsonAtomic } from '../fsx.js';
+import { ensureConfinedDirectory, inspectConfinedPath, ManagedPathSafetyError } from '../managed-path-safety.js';
+import { DESIGN_DEFAULTS } from './types.js';
+export const DECISION_CONFIG_SCHEMA = 'sks.jev-decision-config.v1';
+const CONFIG_DIRNAME = 'decisions';
+export function decisionPaths(env = process.env) {
+    const sksHome = path.resolve(env.SKS_HOME || path.join(env.HOME || os.homedir(), '.sneakoscope'));
+    const configDir = path.join(sksHome, CONFIG_DIRNAME);
+    return {
+        sksHome,
+        configDir,
+        configPath: path.join(configDir, 'config.json')
+    };
+}
+export function defaultDecisionConfig() {
+    return {
+        schema: DECISION_CONFIG_SCHEMA,
+        mode: DESIGN_DEFAULTS.mode,
+        provider: 'openrouter',
+        model: DESIGN_DEFAULTS.model,
+        consentCloud: false,
+        consentAt: null,
+        capabilities: {
+            context: capability(false, false, 'not_enabled'),
+            plan: capability(false, false, 'not_enabled'),
+            recovery: capability(false, false, 'unsupported_no_sks_handler')
+        },
+        updatedAt: null
+    };
+}
+export async function readDecisionConfig(env = process.env) {
+    const paths = decisionPaths(env);
+    const current = await readJson(paths.configPath, null).catch(() => null);
+    return current ? normalizeConfig(current) : defaultDecisionConfig();
+}
+export async function writeDecisionConfig(patch, env = process.env) {
+    const paths = decisionPaths(env);
+    const current = await readDecisionConfig(env);
+    const next = {
+        ...current,
+        ...(patch.mode === undefined ? {} : { mode: patch.mode }),
+        ...(patch.model === undefined ? {} : { model: patch.model }),
+        ...(patch.consentCloud === undefined ? {} : { consentCloud: patch.consentCloud }),
+        ...(patch.consentAt === undefined ? {} : { consentAt: patch.consentAt }),
+        capabilities: {
+            context: patch.capabilities?.context || current.capabilities.context,
+            plan: patch.capabilities?.plan || current.capabilities.plan,
+            recovery: current.capabilities.recovery
+        },
+        updatedAt: nowIso()
+    };
+    if (next.mode !== 'off' && next.mode !== 'jev')
+        throw new Error(`invalid_decision_mode:${String(next.mode)}`);
+    if (next.mode === 'jev' && next.consentCloud !== true)
+        throw new Error('jev_cloud_consent_required');
+    if (next.model !== DESIGN_DEFAULTS.model)
+        throw new Error(`unsupported_decision_model:${next.model}`);
+    await fsp.mkdir(paths.sksHome, { recursive: true });
+    await ensureConfinedDirectory(paths.sksHome, paths.configDir);
+    const inspected = await inspectConfinedPath(paths.sksHome, paths.configPath);
+    if (inspected.leafSymlink) {
+        throw new ManagedPathSafetyError('managed_path_leaf_symlink_refused', inspected.path);
+    }
+    await writeJsonAtomic(inspected.path, next, { mode: 0o600 });
+    return next;
+}
+export function jevEnabled(config) {
+    return config.mode === 'jev' && config.consentCloud === true;
+}
+function normalizeConfig(raw) {
+    const fallback = defaultDecisionConfig();
+    if (!isRecord(raw) || raw.schema !== DECISION_CONFIG_SCHEMA)
+        return fallback;
+    const mode = raw.mode === 'jev' ? 'jev' : 'off';
+    const consentCloud = raw.consentCloud === true;
+    return {
+        schema: DECISION_CONFIG_SCHEMA,
+        mode: mode === 'jev' && consentCloud ? 'jev' : 'off',
+        provider: 'openrouter',
+        model: typeof raw.model === 'string' && raw.model.trim() ? raw.model.trim() : DESIGN_DEFAULTS.model,
+        consentCloud,
+        consentAt: typeof raw.consentAt === 'string' ? raw.consentAt : null,
+        capabilities: {
+            context: normalizeCapability(raw.capabilities, 'context', fallback.capabilities.context),
+            plan: normalizeCapability(raw.capabilities, 'plan', fallback.capabilities.plan),
+            recovery: capability(false, false, 'unsupported_no_sks_handler')
+        },
+        updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : null
+    };
+}
+function normalizeCapability(raw, key, fallback) {
+    if (!isRecord(raw) || !isRecord(raw[key]))
+        return fallback;
+    const row = raw[key];
+    return {
+        ready: row.ready === true,
+        promoted: row.promoted === true,
+        reason: typeof row.reason === 'string' ? row.reason : fallback.reason
+    };
+}
+function capability(ready, promoted, reason) {
+    return { ready, promoted, reason };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/core/decisions/evaluation.js

@@ -0,0 +1,62 @@
+export function percentile(values, p) {
+    const sorted = values.filter((value) => Number.isFinite(value)).sort((left, right) => left - right);
+    if (!sorted.length)
+        return null;
+    const rank = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[rank] ?? null;
+}
+export const EVALUATION_SCHEMA = 'sks.jev-evaluation.v1';
+export function buildEvaluationReport(input) {
+    const unavailable = [];
+    const rows = [...input.rows];
+    if (rows.length === 0)
+        unavailable.push('no_labeled_tasks');
+    const success = rows.map((row) => row.success).filter((value) => value !== null);
+    const escaped = rows.map((row) => row.escapedFailure).filter((value) => value !== null);
+    const wall = rows.map((row) => row.wallClockMs).filter((value) => Number.isFinite(value));
+    const overhead = rows.map((row) => row.jevOverheadMs).filter((value) => Number.isFinite(value));
+    const tokenKnown = rows.every((row) => row.tokenEvidence === 'provider_response');
+    if (!tokenKnown)
+        unavailable.push('token_savings_unavailable');
+    const inputTokens = tokenKnown
+        ? sum(rows.map((row) => row.inputTokens))
+        : null;
+    const outputTokens = tokenKnown
+        ? sum(rows.map((row) => row.outputTokens))
+        : null;
+    const cost = rows.some((row) => row.reportedCost === null)
+        ? null
+        : sum(rows.map((row) => row.reportedCost));
+    if (cost === null)
+        unavailable.push('cost_unavailable');
+    const successes = rows.filter((row) => row.success === true).length;
+    const costPerSuccess = cost === null || successes === 0 ? null : cost / successes;
+    const coverage = rows.filter((row) => row.coveragePreserved).length;
+    return {
+        schema: EVALUATION_SCHEMA,
+        evidenceLevel: input.evidenceLevel || 'synthetic',
+        live: input.live === true,
+        arms: [...new Set(rows.map((row) => row.arm))],
+        taskCount: rows.length,
+        metrics: {
+            taskSuccessRate: success.length ? success.filter(Boolean).length / success.length : null,
+            escapedFailureRate: escaped.length ? escaped.filter(Boolean).length / escaped.length : null,
+            wallClockP50Ms: percentile(wall, 50),
+            wallClockP95Ms: percentile(wall, 95),
+            jevOverheadP50Ms: percentile(overhead, 50),
+            llmRejudgeCalls: rows.reduce((sumValue, row) => sumValue + row.llmRejudgeCalls, 0),
+            inputTokens,
+            outputTokens,
+            reportedCost: cost,
+            costPerSuccessfulTask: costPerSuccess,
+            coveragePreservedRate: rows.length ? coverage / rows.length : null
+        },
+        unavailableReasons: [...unavailable],
+        receipts: [...(input.receipts || [])]
+    };
+}
+function sum(values) {
+    if (values.some((value) => value === null || !Number.isFinite(value)))
+        return null;
+    return values.reduce((total, value) => total + (value || 0), 0);
+}

package/dist/core/decisions/integration.js

@@ -0,0 +1,297 @@
+import { sha256 } from '../fsx.js';
+import { resolveOpenRouterApiKey } from '../providers/openrouter/openrouter-secret-store.js';
+import { jevEnabled, readDecisionConfig } from './config.js';
+import { requestOpenRouterDecision } from './openrouter.js';
+import { compileDecision } from './policy.js';
+import { buildDecisionBundle, validatePlanCoverage } from './questions.js';
+import { applyRecoveryEffect, listProductionRecoveryCandidates } from './recovery.js';
+import { assembleRoutingSelection, buildRoutingCandidates } from './routing.js';
+import { buildDecisionReceipt } from './receipt.js';
+import { applyOptionalContextSelection, graphFileDigest, hydrateContextCandidates, sourceSnapshotDigest } from './state.js';
+import { DESIGN_DEFAULTS, POLICY_REVISION, UNKNOWN_USAGE } from './types.js';
+let testOverrides = null;
+const appliedEffects = new Set();
+export function setDecisionTestOverrides(overrides) {
+    testOverrides = overrides;
+}
+function activeOverrides() {
+    return process.env.SKS_JEV_DECISION_TEST_OVERRIDES === '1' ? testOverrides : null;
+}
+export async function decideOfficialSubagentPreparation(input) {
+    const started = Date.now();
+    try {
+        return await decideOfficialSubagentPreparationInner(input, started);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AssertionError')
+            throw error;
+        return keep(input, 'transport_error', started);
+    }
+}
+async function decideOfficialSubagentPreparationInner(input, started) {
+    const overrides = activeOverrides();
+    const env = input.env || process.env;
+    const config = overrides?.config ?? await readDecisionConfig(env);
+    const baseline = keep(input, 'off', started);
+    if (!jevEnabled(config)) {
+        overrides?.observe?.({ mode: config.mode, eligible: false, compiled: baseline.compiled, receipt: baseline.receipt });
+        return baseline;
+    }
+    const resolved = await resolveOpenRouterApiKey({ env });
+    if (!resolved.key) {
+        const missing = keep(input, 'missing_key', started);
+        overrides?.observe?.({ mode: config.mode, eligible: false, compiled: missing.compiled, receipt: missing.receipt });
+        return missing;
+    }
+    const contextCandidates = config.capabilities.context.ready
+        ? await hydrateContextCandidates(input.root, input.attention, input.changedPaths || [])
+        : [];
+    const planCandidates = config.capabilities.plan.ready && input.requestedSource === 'automatic'
+        ? buildAutomaticPlanCandidates(input)
+        : [];
+    const routingCandidates = input.requestedSource === 'automatic'
+        ? buildRoutingCandidates({ roles: input.routingRoles || [] })
+        : [];
+    const recoveryCandidates = config.capabilities.recovery.ready
+        ? [...listProductionRecoveryCandidates()]
+        : [];
+    const optionalContext = contextCandidates.filter((row) => !row.pinned && row.excerpt);
+    const eligible = planCandidates.length > 1 || routingCandidates.length > 0 || optionalContext.length > 0 || recoveryCandidates.length > 0;
+    if (!eligible) {
+        const compiled = keep(input, 'no_alternative', started);
+        overrides?.observe?.({ mode: config.mode, eligible: false, compiled: compiled.compiled, receipt: compiled.receipt });
+        return compiled;
+    }
+    const sourceDigest = await sourceSnapshotDigest(input.root);
+    const graphDigest = input.attention?.snapshot_hash || await graphFileDigest(input.root);
+    const bundle = buildDecisionBundle({
+        projectId: sha256(input.root).slice(0, 32),
+        workflowRunId: input.workflowRunId,
+        workflowRevision: input.workflowRevision,
+        sourceDigest,
+        graphDigest,
+        goal: input.goal,
+        planCandidates,
+        contextCandidates,
+        recoveryCandidates,
+        routingCandidates,
+        baselinePlanId: planCandidates[0]?.id ?? null,
+        requiredSliceIds: planCandidates[0]?.sliceIds ?? input.slices.map((slice) => slice.id),
+        requiredVerificationIds: ['review_coverage']
+    });
+    const fetchImpl = input.fetchImpl || overrides?.fetchImpl;
+    const transport = await requestOpenRouterDecision(bundle, {
+        env,
+        deadlineMs: input.deadlineMs ?? DESIGN_DEFAULTS.deadlineMs,
+        ...(fetchImpl ? { fetchImpl } : {}),
+        ...(input.signal ? { signal: input.signal } : {})
+    });
+    const compiled = transport.ok
+        ? compileDecision(bundle, transport.response)
+        : {
+            kind: 'keep_baseline',
+            binding: bundle.binding,
+            reason: transport.reason,
+            usage: transport.usage
+        };
+    const applied = compiled.kind === 'apply'
+        ? applyEffects(input.attention, contextCandidates, planCandidates, compiled)
+        : {
+            attention: input.attention,
+            selectedPlan: null,
+            selectedRouting: null,
+            selectedContextIds: null,
+            consumptionEvidence: null
+        };
+    const receipt = buildDecisionReceipt({
+        binding: bundle.binding,
+        compiled,
+        result: compiled.kind === 'apply' ? 'applied' : 'kept_baseline',
+        reason: compiled.kind === 'apply' ? compiled.effects.map((effect) => effect.kind).join(',') : compiled.reason,
+        elapsedMs: Date.now() - started,
+        cacheHit: transport.ok && transport.cacheHit,
+        resolvedModel: transport.ok ? transport.resolvedModel : null,
+        responseId: transport.ok ? transport.responseId : null,
+        consumptionEvidence: applied.consumptionEvidence,
+        env
+    });
+    const result = {
+        compiled,
+        receipt,
+        attention: applied.attention,
+        selectedPlan: applied.selectedPlan,
+        selectedRouting: applied.selectedRouting,
+        selectedContextIds: applied.selectedContextIds,
+        llmRejudgeCalls: 0,
+        bundle
+    };
+    overrides?.observe?.({ mode: config.mode, eligible: true, compiled, receipt });
+    return result;
+}
+export async function consultJevTurnModel(input) {
+    const overrides = activeOverrides();
+    const env = input.env || process.env;
+    const config = overrides?.config ?? await readDecisionConfig(env);
+    if (!jevEnabled(config))
+        return { called: false, model: null, reason: 'off' };
+    const resolved = await resolveOpenRouterApiKey({ env });
+    if (!resolved.key)
+        return { called: false, model: null, reason: 'missing_key' };
+    const prompt = String(input.prompt || '').trim();
+    if (!prompt)
+        return { called: false, model: null, reason: 'empty_prompt' };
+    const bundle = buildDecisionBundle({
+        projectId: sha256(input.root).slice(0, 32),
+        workflowRunId: 'turn',
+        workflowRevision: 'turn',
+        sourceDigest: 'turn',
+        graphDigest: null,
+        goal: prompt,
+        routingCandidates: [{ id: 'turn', summary: prompt.slice(0, 240) }]
+    });
+    const transport = await requestOpenRouterDecision(bundle, {
+        env,
+        deadlineMs: DESIGN_DEFAULTS.deadlineMs,
+        ...(overrides?.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {})
+    });
+    if (!transport.ok)
+        return { called: true, model: null, reason: transport.reason };
+    const compiled = compileDecision(bundle, transport.response);
+    if (compiled.kind !== 'apply')
+        return { called: true, model: null, reason: compiled.reason };
+    const selected = assembleRoutingSelection(compiled.effects.flatMap((effect) => (effect.kind === 'select_routing' ? [{ roleId: effect.roleId, model: effect.model }] : [])));
+    const model = selected?.models.turn || null;
+    return { called: true, model, reason: model ? 'applied' : 'keep_baseline' };
+}
+export function effectAlreadyConsumed(identity) {
+    return appliedEffects.has(identity);
+}
+export function markEffectConsumed(identity) {
+    if (appliedEffects.has(identity))
+        return false;
+    if (appliedEffects.size >= 256) {
+        const oldest = appliedEffects.values().next().value;
+        if (oldest !== undefined)
+            appliedEffects.delete(oldest);
+    }
+    appliedEffects.add(identity);
+    return true;
+}
+export async function dispatchBoundRecovery(input) {
+    if (!markEffectConsumed(input.consumptionIdentity)) {
+        return { invoked: false, reason: 'duplicate_delivery', consumptionEvidence: null };
+    }
+    const result = await applyRecoveryEffect(input);
+    if (!result.ok)
+        return { invoked: false, reason: result.reason, consumptionEvidence: null };
+    return { invoked: true, reason: 'applied', consumptionEvidence: result.consumptionEvidence };
+}
+function applyEffects(attention, contextCandidates, planCandidates, compiled) {
+    let nextAttention = attention;
+    let selectedPlan = null;
+    let selectedContextIds = null;
+    const evidence = [];
+    const routingEffects = [];
+    for (const effect of compiled.effects) {
+        if (effect.kind === 'select_optional_context') {
+            nextAttention = applyOptionalContextSelection(attention, contextCandidates, effect.keepIds);
+            selectedContextIds = effect.keepIds;
+            evidence.push(`context:${effect.keepIds.join(',')}`);
+        }
+        if (effect.kind === 'select_plan') {
+            selectedPlan = planCandidates.find((row) => row.id === effect.planId) || null;
+            if (selectedPlan)
+                evidence.push(`plan:${selectedPlan.id}`);
+        }
+        if (effect.kind === 'select_routing') {
+            routingEffects.push({ roleId: effect.roleId, model: effect.model });
+        }
+    }
+    const selectedRouting = assembleRoutingSelection(routingEffects);
+    if (selectedRouting) {
+        evidence.push(...Object.entries(selectedRouting.models).map(([roleId, model]) => `routing:${roleId}=${model}`));
+    }
+    return {
+        attention: nextAttention,
+        selectedPlan,
+        selectedRouting,
+        selectedContextIds,
+        consumptionEvidence: evidence.length ? evidence.join('|') : null
+    };
+}
+function buildAutomaticPlanCandidates(input) {
+    const slices = input.slices.filter((slice) => slice.id);
+    const sliceIds = slices.map((slice) => slice.id);
+    const workerCount = Math.max(1, input.requestedSubagents);
+    if (workerCount < 2)
+        return [];
+    const verification = ['review_coverage'];
+    const covered = sliceIds.length > 0 ? sliceIds : ['parent_owned_decomposition'];
+    const baselineGroups = slices.length > 0
+        ? slices.map((slice, index) => ({
+            id: `G${index + 1}`,
+            sliceIds: [slice.id],
+            role: slice.agent || (slice.kind === 'expert' ? 'expert' : 'worker'),
+            effort: slice.kind === 'expert' ? 'max' : 'low'
+        }))
+        : [{ id: 'G1', sliceIds: covered, role: 'expert', effort: 'max' }];
+    const baseline = {
+        id: 'baseline',
+        summary: sliceIds.length > 0
+            ? `Execute every required slice with ${workerCount} permitted workers.`
+            : `Execute the automatic parent-owned work with ${workerCount} permitted workers. The parent still decomposes slices.`,
+        sliceIds: covered,
+        groups: baselineGroups,
+        workerCount,
+        requiredVerificationIds: verification
+    };
+    const grouped = {
+        id: 'grouped',
+        summary: sliceIds.length > 0
+            ? 'Execute every required slice in one permitted worker group, preserving full coverage.'
+            : 'Execute the automatic parent-owned work in one permitted worker group. The parent still decomposes slices.',
+        sliceIds: covered,
+        groups: [{ id: 'G1', sliceIds: covered, role: 'expert', effort: 'max' }],
+        workerCount: 1,
+        requiredVerificationIds: verification
+    };
+    const candidates = [baseline, grouped].filter((candidate) => validatePlanCoverage(covered, candidate).length === 0);
+    const workerCounts = new Set(candidates.map((candidate) => candidate.workerCount));
+    if (candidates.length < 2 || workerCounts.size < 2)
+        return [];
+    return candidates;
+}
+function keep(input, reason, started) {
+    const compiled = {
+        kind: 'keep_baseline',
+        binding: {
+            projectId: sha256(input.root).slice(0, 32),
+            workflowRunId: input.workflowRunId,
+            workflowRevision: input.workflowRevision,
+            sourceDigest: 'uncomputed',
+            graphDigest: input.attention?.snapshot_hash ?? null,
+            candidateDigest: 'none',
+            questionDigest: 'none',
+            policyRevision: POLICY_REVISION,
+            requestedModel: DESIGN_DEFAULTS.model
+        },
+        reason,
+        usage: { ...UNKNOWN_USAGE }
+    };
+    return {
+        compiled,
+        receipt: buildDecisionReceipt({
+            binding: compiled.binding,
+            compiled,
+            result: 'kept_baseline',
+            reason,
+            elapsedMs: Date.now() - started
+        }),
+        attention: input.attention,
+        selectedPlan: null,
+        selectedRouting: null,
+        selectedContextIds: null,
+        llmRejudgeCalls: 0,
+        bundle: null
+    };
+}