@aiwg/cli 2026.10.0 → 2026.10.1

package/dist/src/cli/handlers/decision.js

@@ -1,10 +1,11 @@
-import { decisionCapabilities, evaluateRequestPath, listPatterns, livePlan, materializeSyntheticClassificationSetup, runOfflinePattern, showPattern, syntheticClassificationSetup, validateDecisionInput, } from '../../decision/driver.js';
+import { askDecision, DecisionAskUsageError, decisionCapabilities, evaluateRequestPath, listPatterns, livePlan, materializeSyntheticClassificationSetup, readDecisionContextFile, runOfflinePattern, setupJev, showPattern, syntheticClassificationSetup, validateDecisionInput, } from '../../decision/driver.js';
 function jsonResult(value, exitCode = 0) {
     return { exitCode, message: JSON.stringify(value, null, 2), rawOutput: true };
 }
 function usage() {
     return [
         'Usage: aiwg decision <capabilities|status|patterns|validate|evaluate|setup> [options]',
+        '       aiwg decision ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5) [--context <text> | --context-file <path> | --context-stdin] [--threshold 0.8] [--timeout-ms 15000] [--json]',
         '',
         'Commands:',
         '  capabilities|status                 Show offline readiness, primitives, config and feature availability',
@@ -15,6 +16,8 @@ function usage() {
         '  validate <request|definition|ruleset|binding> <path>',
         '  evaluate --request <path> [--host-policy-module <path>]',
         '  setup synthetic-classification [--output-dir <dir>]',
+        '  setup jev [--token-stdin] [--region <r>] [--endpoint <url>] [--verify] [--remove]',
+        '  ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5)',
     ].join('\n');
 }
 function takeOption(args, name) {
@@ -23,11 +26,90 @@ function takeOption(args, name) {
         return undefined;
     return args[index + 1];
 }
+function takeRequiredOption(args, name) {
+    const value = takeOption(args, name);
+    if (!value || value.startsWith('--'))
+        throw new DecisionAskUsageError(`missing-${name.slice(2)}`, `${name} requires a value`);
+    return value;
+}
 function patternId(value) {
     if (!value)
         throw new Error('Pattern id is required');
     return value;
 }
+function flagCount(args, names) {
+    return args.filter(arg => names.includes(arg)).length;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseNumber(value, name) {
+    if (value === undefined)
+        throw new DecisionAskUsageError(`missing-${name.slice(2)}`, `${name} requires a value`);
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new DecisionAskUsageError(`invalid-${name.slice(2)}`, `${name} must be numeric`);
+    return parsed;
+}
+function parseScale(value) {
+    if (!value)
+        throw new DecisionAskUsageError('invalid-scale', '--scale requires a range like 1-5');
+    const match = /^(-?\d+)-(-?\d+)$/.exec(value);
+    if (!match)
+        throw new DecisionAskUsageError('invalid-scale', '--scale requires a range like 1-5');
+    return { low: Number(match[1]), high: Number(match[2]) };
+}
+async function decisionSetupJev(rest) {
+    const token = rest.includes('--token-stdin') ? (await readStdin()).trim() : undefined;
+    const result = await setupJev({
+        token,
+        region: takeOption(rest, '--region'),
+        endpoint: takeOption(rest, '--endpoint'),
+        verify: rest.includes('--verify'),
+        remove: rest.includes('--remove'),
+    }, { env: process.env });
+    return jsonResult(result);
+}
+async function decisionAsk(ctx) {
+    const args = ctx.args.slice(1);
+    const modeCount = flagCount(args, ['--yes-no']) + (args.includes('--choices') ? 1 : 0) + (args.includes('--scale') ? 1 : 0);
+    if (modeCount !== 1)
+        throw new DecisionAskUsageError('invalid-mode', 'Select exactly one of --yes-no, --choices, or --scale');
+    const contextModes = flagCount(args, ['--context', '--context-file', '--context-stdin']);
+    if (contextModes > 1)
+        throw new DecisionAskUsageError('invalid-context', 'Select at most one context source');
+    const question = args.includes('--question') ? takeRequiredOption(args, '--question') : '';
+    let context = takeOption(args, '--context');
+    if (args.includes('--context') && (context === undefined || context.startsWith('--'))) {
+        throw new DecisionAskUsageError('missing-context', '--context requires text');
+    }
+    if (args.includes('--context-file')) {
+        const filePath = takeRequiredOption(args, '--context-file');
+        context = await readDecisionContextFile(filePath);
+    }
+    if (args.includes('--context-stdin'))
+        context = await readStdin();
+    const choices = args.includes('--choices') ? takeRequiredOption(args, '--choices') : undefined;
+    const scale = args.includes('--scale') ? parseScale(takeOption(args, '--scale')) : null;
+    const input = {
+        question,
+        mode: args.includes('--yes-no') ? { kind: 'yes-no' }
+            : choices !== undefined ? { kind: 'choices', choices: choices.split(',').map(value => value.trim()).filter(Boolean) }
+                : { kind: 'scale', ...scale },
+        ...(context === undefined ? {} : { context }),
+        ...(args.includes('--threshold') ? { threshold: parseNumber(takeOption(args, '--threshold'), '--threshold') } : {}),
+        ...(args.includes('--timeout-ms') ? { timeoutMs: parseNumber(takeOption(args, '--timeout-ms'), '--timeout-ms') } : {}),
+    };
+    const result = await askDecision(input, { env: process.env });
+    if (args.includes('--json'))
+        return jsonResult(result);
+    if (result.status === 'fallback')
+        return { exitCode: 0, message: `FALLBACK to LLM: ${result.reason}`, rawOutput: true };
+    return { exitCode: 0, message: `${String(result.answer)} (confidence ${result.confidence?.toFixed(2) ?? 'unknown'}, ${result.model ?? 'unknown-model'})`, rawOutput: true };
+}
 async function executeDecision(ctx) {
     const [command, subcommand, ...rest] = ctx.args;
     const options = { cwd: ctx.cwd, frameworkRoot: ctx.frameworkRoot, env: process.env };
@@ -36,6 +118,8 @@ async function executeDecision(ctx) {
             return { exitCode: 0, message: usage(), rawOutput: true };
         if (command === 'capabilities' || command === 'status')
             return jsonResult(decisionCapabilities(options));
+        if (command === 'ask')
+            return await decisionAsk(ctx);
         if (command === 'patterns') {
             if (subcommand === 'list')
                 return jsonResult(listPatterns());
@@ -70,9 +154,14 @@ async function executeDecision(ctx) {
                 return jsonResult(await materializeSyntheticClassificationSetup(outputDir, {}, options));
             return jsonResult(syntheticClassificationSetup({}, options));
         }
+        if (command === 'setup' && subcommand === 'jev')
+            return await decisionSetupJev(rest);
         return { exitCode: 2, message: usage(), rawOutput: true };
     }
     catch (error) {
+        if (error instanceof DecisionAskUsageError) {
+            return { exitCode: 2, message: JSON.stringify({ schema: 'aiwg-decision-error/v1', reason: error.reason, message: error.message }, null, 2), rawOutput: true };
+        }
         return { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
     }
 }

package/dist/src/decision/adapters/jev.js

@@ -453,7 +453,11 @@ function normalizeAnswer(request, body, questionId) {
                 throw new DecisionValidationError('Score legend does not match declared levels');
         });
         const mean = Object.entries(distribution).reduce((sum, [index, probability]) => sum + Number(index) * probability, 0);
-        if (Math.abs(mean - answer.score) > 0.02)
+        // Jev reports probabilities and the score to two decimals, so each probability carries up to
+        // 0.005 of rounding error, weighted by its index, plus 0.005 on the score itself.
+        const indexSum = Object.keys(distribution).reduce((sum, index) => sum + Number(index), 0);
+        const tolerance = Math.max(0.02, 0.005 * indexSum + 0.005) + 1e-9;
+        if (Math.abs(mean - answer.score) > tolerance)
             throw new DecisionValidationError('Score is not the distribution weighted mean');
         validateDecisionValue(request.definition, answer.score);
         return success(answer.score, model, usage, uncertainty(answer.confidence, distribution, 'typesafe-distribution-v1'));

package/dist/src/decision/ask.js

@@ -0,0 +1,352 @@
+import { readFile } from 'node:fs/promises';
+import { JEV_ENDPOINT, JevDecisionAdapter } from './adapters/jev.js';
+import { evaluateDecisionRuleset } from './evaluate.js';
+import { artifactPin } from './validate.js';
+import { JEV_CREDENTIAL_REF, JEV_DEFAULT_REGION, lookupJevCredential, removeJevCredentialFile, resolveJevCredentialBytes, writeJevCredentialFile, } from './jev-credentials.js';
+const CONTEXT_LIMIT_BYTES = 32 * 1024;
+const MODEL = 'jev-latest';
+const PURPOSE = 'agent-bounded-decision';
+const INPUT_SCHEMA = {
+    type: 'object',
+    properties: { message: { type: 'string', minLength: 1 } },
+    required: ['message'],
+    additionalProperties: false,
+};
+export class DecisionAskUsageError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'DecisionAskUsageError';
+    }
+}
+function usageError(reason, message) {
+    throw new DecisionAskUsageError(reason, message);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function validateQuestion(question) {
+    if (!question.trim())
+        usageError('question-required', 'decision ask requires --question <q>');
+}
+export function validateDecisionAskInput(input) {
+    validateQuestion(input.question);
+    if (input.context !== undefined && byteLength(input.context) > CONTEXT_LIMIT_BYTES) {
+        usageError('context-too-large', 'decision ask context exceeds 32 KiB');
+    }
+    const threshold = input.threshold ?? 0.8;
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        usageError('invalid-threshold', '--threshold must be a probability from 0 to 1');
+    }
+    const timeoutMs = input.timeoutMs ?? 15_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        usageError('invalid-timeout', '--timeout-ms must be a positive integer');
+    if (input.mode.kind === 'choices') {
+        if (input.mode.choices.length < 2 || input.mode.choices.length > 255)
+            usageError('invalid-choices', '--choices requires 2..255 ids');
+        const seen = new Set();
+        for (const { id, description } of input.mode.choices.map(parseChoice)) {
+            if (!/^[A-Za-z0-9_.-]{1,64}$/.test(id))
+                usageError('invalid-choices', 'choice ids must match [A-Za-z0-9_.-]{1,64}');
+            if (description !== undefined && (!description || description.length > 200)) {
+                usageError('invalid-choices', 'choice descriptions after = must be 1..200 characters');
+            }
+            if (seen.has(id))
+                usageError('invalid-choices', 'choice ids must not contain duplicates');
+            seen.add(id);
+        }
+    }
+    if (input.mode.kind === 'scale') {
+        const count = input.mode.high - input.mode.low + 1;
+        if (!Number.isInteger(input.mode.low) || !Number.isInteger(input.mode.high) || input.mode.low > input.mode.high || count < 2 || count > 10) {
+            usageError('invalid-scale', '--scale must be an integer range like 1-5 with at most 10 levels');
+        }
+    }
+}
+function usage(usageValue) {
+    if (!usageValue)
+        return null;
+    return { inputTokens: usageValue.inputTokens, outputTokens: usageValue.outputTokens };
+}
+function fallback(reason, latencyMs, attempt) {
+    return {
+        schema: 'aiwg-decision-ask/v1',
+        status: 'fallback',
+        answer: null,
+        confidence: null,
+        fallback: 'llm',
+        reason,
+        model: attempt?.actualModel ?? null,
+        usage: usage(attempt?.usage),
+        latencyMs,
+    };
+}
+/** A choice is `id` or `id=description`; the description tells Jev what the option means. */
+function parseChoice(entry) {
+    const separator = entry.indexOf('=');
+    if (separator < 0)
+        return { id: entry.trim() };
+    return { id: entry.slice(0, separator).trim(), description: entry.slice(separator + 1).trim() };
+}
+function scaleLevel(value, low, high) {
+    const edge = value === low ? ' (lowest)' : value === high ? ' (highest)' : '';
+    return `Level ${value} on a ${low} to ${high} scale${edge}.`;
+}
+function answerKind(mode) {
+    if (mode.kind === 'yes-no')
+        return {
+            kind: 'truth-probability',
+            trueDescription: 'Yes.',
+            falseDescription: 'No.',
+        };
+    if (mode.kind === 'choices')
+        return {
+            kind: 'choice',
+            options: mode.choices.map(parseChoice).map(({ id, description }) => ({ id, description: description ?? id })),
+        };
+    return {
+        kind: 'ordinal-score',
+        levels: Array.from({ length: mode.high - mode.low + 1 }, (_, index) => scaleLevel(mode.low + index, mode.low, mode.high)),
+    };
+}
+function definition(input) {
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionDefinition',
+        metadata: { id: 'aiwg.ask.answer', version: '1.0.0', description: 'Bounded advisory ask decision' },
+        spec: {
+            purpose: PURPOSE,
+            inputSchema: INPUT_SCHEMA,
+            question: input.question,
+            answer: answerKind(input.mode),
+            requiredCapabilities: [input.mode.kind === 'yes-no' ? 'truth-probability' : input.mode.kind === 'choices' ? 'choice' : 'ordinal-score'],
+        },
+    };
+}
+function ruleset(definitionValue) {
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionRuleset',
+        metadata: { id: 'aiwg.ask.ruleset', version: '1.0.0', description: 'Bounded advisory ask ruleset' },
+        spec: {
+            purpose: PURPOSE,
+            inputSchema: INPUT_SCHEMA,
+            evaluations: [{ alias: 'answer', decision: artifactPin(definitionValue), inputPointer: '' }],
+            rules: [{
+                    id: 'answered',
+                    priority: 1,
+                    when: { op: 'exists', left: { source: 'decision', alias: 'answer', pointer: '/value' } },
+                    outcome: 'answered',
+                }],
+            composition: 'first-match',
+            conflict: 'review',
+            defaultOutcome: 'fallback',
+            failureOutcome: 'fallback',
+            outputSchema: { enum: ['answered', 'fallback'] },
+        },
+    };
+}
+function binding(rulesetValue, primitive, timeoutMs) {
+    const target = {
+        adapter: 'jev',
+        adapterVersion: '1.0.0',
+        model: MODEL,
+        requiredCapabilities: [primitive],
+        acceptance: { mode: 'typed-value' },
+        timeoutMs,
+        retry: { maxRetries: 0, initialDelayMs: 250, maxDelayMs: 2_000 },
+        credentialRef: JEV_CREDENTIAL_REF,
+    };
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionBinding',
+        metadata: { id: 'aiwg.ask.binding', version: '1.0.0', description: 'Bounded advisory ask Jev binding' },
+        spec: {
+            ruleset: artifactPin(rulesetValue),
+            totalTimeoutMs: timeoutMs,
+            maxAttempts: 1,
+            concurrency: 1,
+            evaluations: { answer: { targets: [target], fallbackOn: [] } },
+        },
+    };
+}
+function projectionPolicy(region, endpoint) {
+    const origin = new URL(endpoint ?? JEV_ENDPOINT).origin;
+    return {
+        version: '1.0.0',
+        provider: 'jev',
+        model: MODEL,
+        origin,
+        region,
+        purpose: PURPOSE,
+        allowIncompleteContext: false,
+        fields: [{
+                pointer: '/message',
+                output: 'message',
+                source: 'operator',
+                subject: 'aiwg-decision-ask',
+                trust: 'untrusted',
+                sensitivity: 'internal',
+                purpose: PURPOSE,
+                retentionClass: 'ephemeral',
+                accessScopes: ['decision-runtime'],
+                exportPolicy: 'sanitized',
+                deletionPolicy: 'erase',
+                backupPolicy: 'not-persisted',
+                allowedProviders: ['jev'],
+                allowedModels: [MODEL],
+                allowedOrigins: [origin],
+                allowedRegions: [region],
+            }],
+    };
+}
+function contextMessage(input) {
+    return input.context === undefined || input.context === ''
+        ? input.question
+        : `${input.question}\n\nContext:\n${input.context}`;
+}
+function confidenceFor(mode, evaluation) {
+    const uncertainty = evaluation.spec.uncertainty;
+    const value = evaluation.spec.value;
+    if (mode.kind === 'yes-no' && typeof value === 'number')
+        return Math.max(value, 1 - value);
+    if (uncertainty?.distribution && mode.kind === 'choices' && typeof value === 'string')
+        return uncertainty.distribution[value] ?? uncertainty.confidence;
+    if (uncertainty?.distribution && mode.kind === 'scale')
+        return Math.max(...Object.values(uncertainty.distribution));
+    return uncertainty?.confidence ?? null;
+}
+function mostLikelyIndex(distribution) {
+    if (!distribution)
+        return null;
+    let best = null;
+    for (const [index, probability] of Object.entries(distribution)) {
+        if (best === null || probability > (distribution[String(best)] ?? -1))
+            best = Number(index);
+    }
+    return best;
+}
+function publicAnswer(mode, value, distribution) {
+    if (mode.kind === 'yes-no') {
+        const probability = typeof value === 'number' ? value : null;
+        return probability === null ? { answer: null } : { answer: probability >= 0.5, probability };
+    }
+    if (mode.kind === 'scale') {
+        // Jev returns the distribution-weighted mean index; report the most likely level instead.
+        const index = mostLikelyIndex(distribution) ?? (typeof value === 'number' ? Math.round(value) : null);
+        return index === null ? { answer: null } : { answer: mode.low + index };
+    }
+    return typeof value === 'string' ? { answer: value } : { answer: null };
+}
+export async function askDecision(input, options = {}) {
+    validateDecisionAskInput(input);
+    const started = options.now?.() ?? Date.now();
+    let credential;
+    try {
+        credential = await lookupJevCredential(options);
+    }
+    catch {
+        return fallback('not-configured', 0);
+    }
+    if (!credential?.enabled || !credential.token)
+        return fallback('not-configured', 0);
+    const timeoutMs = input.timeoutMs ?? 15_000;
+    const def = definition(input);
+    const rules = ruleset(def);
+    const bind = binding(rules, def.spec.answer.kind, timeoutMs);
+    const adapter = options.adapter ?? options.createAdapter?.({ region: credential.region, endpoint: credential.endpoint })
+        ?? new JevDecisionAdapter({ region: credential.region, ...(credential.endpoint ? {
+                endpoint: credential.endpoint,
+                allowedOrigins: [new URL(credential.endpoint).origin],
+            } : {}) });
+    let result;
+    try {
+        result = await (options.evaluate ?? evaluateDecisionRuleset)({
+            ruleset: rules,
+            binding: bind,
+            definitions: { [def.metadata.id]: def },
+            input: { message: contextMessage(input) },
+            runId: options.runId ?? 'aiwg-decision-ask',
+            invocationId: options.invocationId ?? `ask-${Date.now()}`,
+            adapters: { jev: adapter },
+            resolveCredential: options.resolveCredential ?? (logicalRef => resolveJevCredentialBytes(logicalRef, options)),
+            projection: { resolve: () => projectionPolicy(credential.region, credential.endpoint) },
+        });
+    }
+    catch {
+        return fallback('jev-error', Math.max(0, (options.now?.() ?? Date.now()) - started));
+    }
+    const latencyMs = Math.max(0, (options.now?.() ?? Date.now()) - started);
+    const evaluation = result.spec.evaluations.answer;
+    const attempt = evaluation?.spec.attempts.at(-1);
+    if (!evaluation || evaluation.spec.status !== 'success')
+        return fallback(evaluation?.spec.reason ?? result.spec.reason, latencyMs, attempt);
+    const confidence = confidenceFor(input.mode, evaluation);
+    const threshold = input.threshold ?? 0.8;
+    if (confidence === null || confidence < threshold)
+        return fallback('low-confidence', latencyMs, attempt);
+    const answer = publicAnswer(input.mode, evaluation.spec.value, evaluation.spec.uncertainty?.distribution);
+    return {
+        schema: 'aiwg-decision-ask/v1',
+        status: 'answered',
+        answer: answer.answer,
+        confidence,
+        ...(answer.probability === undefined ? {} : { probability: answer.probability }),
+        fallback: null,
+        reason: 'none',
+        model: attempt?.actualModel ?? null,
+        usage: usage(attempt?.usage),
+        latencyMs,
+    };
+}
+export async function readDecisionContextFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    if (byteLength(content) > CONTEXT_LIMIT_BYTES)
+        usageError('context-too-large', 'decision ask context exceeds 32 KiB');
+    return content;
+}
+export async function setupJev(input = {}, options = {}) {
+    const region = input.region?.trim() || JEV_DEFAULT_REGION;
+    if (input.remove) {
+        await removeJevCredentialFile(options);
+        return {
+            schema: 'aiwg-decision-jev-setup/v1',
+            configured: false,
+            credentialSource: 'file',
+            region,
+            next: ['Run aiwg decision setup jev --token-stdin to configure Jev again.'],
+        };
+    }
+    const environment = options.env ?? process.env;
+    const envToken = environment.JEV_API_KEY?.trim() || environment.AIWG_DECISION_JEV_API_KEY?.trim();
+    const token = input.token?.trim() || envToken;
+    if (!token)
+        usageError('token-required', 'Provide --token-stdin or set JEV_API_KEY or AIWG_DECISION_JEV_API_KEY.');
+    await writeJevCredentialFile({
+        token,
+        region,
+        ...(input.endpoint?.trim() ? { endpoint: input.endpoint.trim() } : {}),
+        enabled: true,
+    }, options);
+    const result = {
+        schema: 'aiwg-decision-jev-setup/v1',
+        configured: true,
+        credentialSource: input.token?.trim() ? 'file' : 'env',
+        region,
+        next: ['Run aiwg decision ask --question "<q>" --yes-no --json.'],
+    };
+    if (input.verify) {
+        const verified = await askDecision({
+            question: 'Is this Jev decision setup verification request well formed?',
+            mode: { kind: 'yes-no' },
+            threshold: 0,
+            timeoutMs: 15_000,
+        }, options);
+        result.verified = verified.status === 'answered';
+        result.model = verified.model;
+        result.usage = verified.usage;
+    }
+    return result;
+}
+//# sourceMappingURL=ask.js.map

package/dist/src/decision/driver.js

@@ -2,7 +2,9 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { askDecision, setupJev, DecisionAskUsageError, readDecisionContextFile, validateDecisionAskInput, } from './ask.js';
 import { assertDecisionEvaluateDispatcherConfig, decisionPatternPacks, getDecisionPatternPack, governedPatternArtifacts, listDecisionPatterns, patternInputSchema, patternOutputSchema, planLiveDecisionPattern, runOfflineDecisionPattern, validateAgainstSchema, validateDecisionDocument, validateDefinition, validateRuleset, } from './index.js';
+export { askDecision, setupJev, readDecisionContextFile, validateDecisionAskInput, DecisionAskUsageError, };
 const DECISION_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const VALIDATION_TARGETS = ['request', 'definition', 'ruleset', 'binding'];
 const OFFLINE_ADAPTER = 'agentic/code/addons/decision-engine/examples/fixture-jev-adapter.mjs';

package/dist/src/decision/index.js

@@ -53,6 +53,8 @@ export * from './sensitivity/index.js';
 export * from './issue-triage/index.js';
 export * from './routing/index.js';
 export * from './interop.js';
+export * from './ask.js';
+export * from './jev-credentials.js';
 export { collectHeldoutStudy, scoreHeldoutStudy } from './heldout/collector.js';
 export { heldoutDigest, heldoutExecutionDigest, planHeldoutCollection, validateHeldoutBundle, heldoutRowsInScope } from './heldout/contract.js';
 //# sourceMappingURL=index.js.map

package/dist/src/decision/jev-credentials.js

@@ -0,0 +1,121 @@
+import { constants } from 'node:fs';
+import { access, chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { JevCredentialError } from './adapters/jev.js';
+export const JEV_CREDENTIAL_REF = 'typesafe-api';
+export const JEV_DEFAULT_REGION = 'us';
+function env(options) {
+    return options.env ?? process.env;
+}
+export function jevCredentialPath(options = {}) {
+    if (options.credentialPath)
+        return options.credentialPath;
+    const configuredHome = options.configHome ?? env(options).XDG_CONFIG_HOME;
+    const base = configuredHome && configuredHome.trim() ? configuredHome : path.join(options.homeDir ?? os.homedir(), '.config');
+    return path.join(base, 'aiwg', 'credentials', 'jev.json');
+}
+function isInsecureMode(mode) {
+    return (mode & 0o077) !== 0;
+}
+function parseRecord(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new JevCredentialError('configuration');
+    const record = parsed;
+    if (typeof record.token !== 'string' || !record.token.trim())
+        throw new JevCredentialError('configuration');
+    if (record.region !== undefined && (typeof record.region !== 'string' || !record.region.trim())) {
+        throw new JevCredentialError('configuration');
+    }
+    if (record.endpoint !== undefined && (typeof record.endpoint !== 'string' || !record.endpoint.trim())) {
+        throw new JevCredentialError('configuration');
+    }
+    if (record.enabled !== undefined && typeof record.enabled !== 'boolean')
+        throw new JevCredentialError('configuration');
+    return {
+        token: record.token,
+        region: typeof record.region === 'string' ? record.region : JEV_DEFAULT_REGION,
+        ...(typeof record.endpoint === 'string' ? { endpoint: record.endpoint } : {}),
+        ...(typeof record.enabled === 'boolean' ? { enabled: record.enabled } : {}),
+    };
+}
+async function readCredentialFile(options = {}) {
+    const credentialPath = jevCredentialPath(options);
+    try {
+        const [fileStat, parentStat] = await Promise.all([stat(credentialPath), stat(path.dirname(credentialPath))]);
+        if (isInsecureMode(fileStat.mode) || isInsecureMode(parentStat.mode))
+            throw new JevCredentialError('denied');
+        return parseRecord(await readFile(credentialPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        if (error instanceof JevCredentialError)
+            throw error;
+        if (error instanceof SyntaxError)
+            throw new JevCredentialError('configuration');
+        throw error;
+    }
+}
+export async function lookupJevCredential(options = {}) {
+    const environment = env(options);
+    const forced = environment.AIWG_DECISION_ENABLED;
+    const envToken = environment.JEV_API_KEY?.trim() || environment.AIWG_DECISION_JEV_API_KEY?.trim();
+    const fileRecord = envToken && (forced === '0' || forced === '1') ? null : await readCredentialFile(options);
+    const enabled = forced === '0' ? false : forced === '1' ? true : fileRecord?.enabled === true;
+    if (envToken)
+        return {
+            source: 'env',
+            token: envToken,
+            region: environment.AIWG_DECISION_JEV_REGION?.trim() || fileRecord?.region || JEV_DEFAULT_REGION,
+            ...(environment.AIWG_DECISION_JEV_ENDPOINT?.trim() ? { endpoint: environment.AIWG_DECISION_JEV_ENDPOINT.trim() }
+                : fileRecord?.endpoint ? { endpoint: fileRecord.endpoint } : {}),
+            enabled,
+        };
+    if (!fileRecord)
+        return null;
+    return { source: 'file', token: fileRecord.token, region: fileRecord.region, ...(fileRecord.endpoint ? { endpoint: fileRecord.endpoint } : {}), enabled };
+}
+export async function resolveJevCredentialBytes(logicalRef, options = {}) {
+    if (logicalRef !== JEV_CREDENTIAL_REF)
+        throw new JevCredentialError('configuration');
+    const credential = await lookupJevCredential(options);
+    if (!credential?.enabled)
+        throw new JevCredentialError('denied');
+    if (!credential.token)
+        throw new JevCredentialError('missing');
+    return new TextEncoder().encode(credential.token);
+}
+export async function writeJevCredentialFile(record, options = {}) {
+    const credentialPath = jevCredentialPath(options);
+    const directory = path.dirname(credentialPath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const tmp = path.join(directory, `.jev.${process.pid}.${randomUUID()}.tmp`);
+    const body = `${JSON.stringify(record, null, 2)}\n`;
+    try {
+        await writeFile(tmp, body, { mode: 0o600, flag: 'wx' });
+        await chmod(tmp, 0o600);
+        await rename(tmp, credentialPath);
+        await chmod(credentialPath, 0o600);
+        return credentialPath;
+    }
+    catch (error) {
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function removeJevCredentialFile(options = {}) {
+    const credentialPath = jevCredentialPath(options);
+    try {
+        await access(credentialPath, constants.F_OK);
+    }
+    catch {
+        return false;
+    }
+    await rm(credentialPath, { force: true });
+    return true;
+}
+//# sourceMappingURL=jev-credentials.js.map

package/dist/src/mcp/tools/decision.mjs

@@ -82,6 +82,21 @@ const SYNTHETIC_SETUP = z.object({
   pattern: z.object({ id: z.string(), version: z.string() }).passthrough(),
   files: z.record(z.string(), z.unknown()),
 }).passthrough();
+const ASK = z.object({
+  schema: z.literal('aiwg-decision-ask/v1'),
+  status: z.enum(['answered', 'fallback']),
+  answer: z.union([z.string(), z.boolean(), z.number()]).nullable(),
+  confidence: z.number().min(0).max(1).nullable(),
+  probability: z.number().min(0).max(1).optional(),
+  fallback: z.enum(['llm']).nullable(),
+  reason: z.string(),
+  model: z.string().nullable(),
+  usage: z.object({
+    inputTokens: z.number().int().nonnegative().nullable(),
+    outputTokens: z.number().int().nonnegative().nullable(),
+  }).nullable(),
+  latencyMs: z.number().nonnegative(),
+}).passthrough();
 
 let driverPromise;
 
@@ -176,6 +191,31 @@ export function registerDecisionToolset(server) {
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
   }, async ({ profile, opt_in }) => (await driver()).evaluateMcpProfile(profile, opt_in, options()), EVALUATE);
 
+  registerJsonTool(server, 'decision-ask', {
+    title: 'Ask bounded Jev decision',
+    description: 'Ask a bounded yes/no, choice, or small ordinal decision. Falls back to the caller on missing setup or low confidence.',
+    inputSchema: {
+      question: z.string().min(1),
+      yes_no: z.boolean().default(false),
+      choices: z.array(z.string()).min(2).max(255).optional().describe('Choice ids, each optionally written as id=description so Jev knows what the option means'),
+      scale: z.object({ low: z.number().int(), high: z.number().int() }).optional(),
+      context: z.string().optional(),
+      threshold: z.number().min(0).max(1).default(0.8),
+      timeout_ms: z.number().int().positive().default(15000),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+  }, async ({ question, yes_no, choices, scale, context, threshold, timeout_ms }) => {
+    const modeCount = (yes_no ? 1 : 0) + (choices ? 1 : 0) + (scale ? 1 : 0);
+    if (modeCount !== 1) throw new Error('Select exactly one of yes_no, choices, or scale');
+    return (await driver()).askDecision({
+      question,
+      mode: yes_no ? { kind: 'yes-no' } : choices ? { kind: 'choices', choices } : { kind: 'scale', low: scale.low, high: scale.high },
+      ...(context === undefined ? {} : { context }),
+      threshold,
+      timeoutMs: timeout_ms,
+    }, options());
+  }, ASK);
+
   registerJsonTool(server, 'decision-setup-synthetic-classification', {
     title: 'Prepare synthetic classification artifacts',
     description: 'Return reviewable pinned synthetic classification artifacts and a dispatcher request.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.10.0",
+  "version": "2026.10.1",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/agents/providers/base.mjs

@@ -1363,13 +1363,13 @@ export function computeAllArtifactBasenames(srcRoot, type) {
     // Soul companions live alongside agents and are deployed with them —
     // keep their stems in the desired set so the prune never removes them.
     add(frameworkArtifacts.souls || []);
-    add(getAddonAgentFiles(aiwgRoot));
+    add(getAddonAgentFiles(aiwgRoot, [], { includeExplicit: true }));
   } else if (type === 'commands') {
     add(frameworkArtifacts.commands);
-    add(getAddonCommandFiles(aiwgRoot));
+    add(getAddonCommandFiles(aiwgRoot, [], { includeExplicit: true }));
   } else if (type === 'rules') {
     add(frameworkArtifacts.rules);
-    add(getAddonRuleFiles(aiwgRoot));
+    add(getAddonRuleFiles(aiwgRoot, [], { includeExplicit: true }));
   }
 
   return stems;
@@ -2264,9 +2264,10 @@ export function collectFrameworkArtifacts(srcRoot, mode, options = {}) {
 /**
  * Discover all addons in the agentic/code/addons directory
  * @param {string} srcRoot - Source root directory
+ * @param {{includeExplicit?: boolean}} [options] - includeExplicit also returns explicitInstall addons
  * @returns {Array<{name: string, path: string, manifest: object}>} - Array of addon info
  */
-export function discoverAddons(srcRoot) {
+export function discoverAddons(srcRoot, { includeExplicit = false } = {}) {
   const addonsDir = path.join(srcRoot, 'agentic', 'code', 'addons');
   if (!fs.existsSync(addonsDir)) return [];
 
@@ -2290,7 +2291,9 @@ export function discoverAddons(srcRoot) {
     if (manifest.devOnly === true) continue;
     // explicitInstall addons deploy only when named (`aiwg use <addon>`), never
     // as part of a framework or `all` bulk deploy (#2641).
-    if (manifest.explicitInstall === true) continue;
+    // The stale-artifact prune passes includeExplicit so a named install's own
+    // files stay in its desired set and are not deleted right after deployment.
+    if (manifest.explicitInstall === true && !includeExplicit) continue;
 
     addons.push({
       name: entry.name,
@@ -2308,8 +2311,8 @@ export function discoverAddons(srcRoot) {
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of agent file paths
  */
-export function getAddonAgentFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonAgentFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {
@@ -2330,8 +2333,8 @@ export function getAddonAgentFiles(srcRoot, excludeAddons = []) {
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of command file paths
  */
-export function getAddonCommandFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonCommandFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {
@@ -2651,8 +2654,8 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
   return names.length + demotedNames.length;
 }
 
-export function getAddonRuleFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonRuleFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {