@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/models/worker-dispatch-offer.js

@@ -0,0 +1,169 @@
+/**
+ * Direct-worker dispatch opt-in offer (#3050).
+ *
+ * `parallelism.worker_dispatch` is off by default (#1359) and nothing told a
+ * user it exists, showed whether their machine could use it, or offered to
+ * turn it on. This module is the single shared place that decides whether
+ * any setup surface should offer it, and renders the matching prompt/hint
+ * text — every surface (`aiwg init`, `aiwg setup project`, `aiwg regenerate`,
+ * `aiwg refresh`, `aiwg doctor --probe-workers`) calls it instead of growing
+ * its own copy.
+ *
+ * Detection is presence-only: each known worker-CLI executable (from the
+ * shipped provider capability registry's `workerAdapter` /
+ * `workerHealthAdapter` process invocations — the same provider ->
+ * executable mapping `resolveDirectBinding()` in `worker-direct-readiness.ts`
+ * resolves bindings from) is checked for a match on `PATH` only. No process
+ * is spawned and no network call is made. This is deliberately narrower
+ * than `worker-direct-readiness.ts`'s version probes
+ * (`probeDirectWorkerVersion` / `boundedVersionProbe`), which spawn
+ * `<executable> ...versionArgv` and are opt-in behind `--probe-workers`;
+ * the offer only needs to know a CLI is present, so it never pays that cost
+ * or crosses that trust boundary.
+ */
+import { accessSync, constants as fsConstants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { loadProviderModelCapabilities } from './provider-policy.js';
+/**
+ * The one command every hint/prompt points at to flip the setting on — this
+ * is also the real re-enable path after a decline: enabling dispatch
+ * directly always clears the offer (see {@link evaluateWorkerDispatchOffer}),
+ * so there is no separate "undo the decline" command to document.
+ */
+export const WORKER_DISPATCH_ENABLE_COMMAND = 'aiwg config set --project parallelism.worker_dispatch true';
+/** Readiness check shared by setup hints and dispatch refusals. */
+export const WORKER_DISPATCH_READINESS_COMMAND = 'aiwg doctor --probe-workers';
+/**
+ * Dotted config path a decline is recorded at. A setup/onboarding
+ * preference, not worker policy — kept out of `parallelism`, which is a
+ * frozen contract fragment (B-OG-29, #3050 review).
+ */
+export const WORKER_DISPATCH_DECLINE_FIELD = 'setup.worker_dispatch_offer';
+/** Minimum number of distinct detected worker CLIs before any surface offers. */
+const MIN_DETECTED_FOR_OFFER = 2;
+/**
+ * Presence-only PATH check for one executable name: no spawn, no network.
+ * Requires a regular file (symlinks are followed by `statSync`) before the
+ * execute-permission check — an `X_OK` search-permission bit also succeeds
+ * for a directory, so without this a directory on `PATH` that merely shares
+ * a worker CLI's name would count as installed (#3050 review item 8).
+ */
+function executableOnPath(name, pathEnv) {
+    const dirs = (pathEnv ?? '').split(delimiter).filter(Boolean);
+    const candidates = process.platform === 'win32' ? [`${name}.exe`, `${name}.cmd`, `${name}.bat`, name] : [name];
+    return dirs.some(dir => candidates.some(candidate => {
+        const target = join(dir, candidate);
+        try {
+            if (!statSync(target).isFile())
+                return false;
+            accessSync(target, fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/**
+ * Every known worker-CLI executable name declared by the shipped capability
+ * registry, deduplicated and sorted. Mirrors the same provider -> executable
+ * mapping `worker-direct-readiness.ts`'s `resolveDirectBinding()` resolves
+ * at dispatch time (`workerAdapter` falling back to `workerHealthAdapter`),
+ * so this list can never drift from what the resolver would actually bind.
+ */
+export function knownWorkerCliExecutables(registry = loadProviderModelCapabilities()) {
+    const names = new Set();
+    for (const provider of Object.values(registry.providers)) {
+        const adapter = provider.workerAdapter ?? provider.workerHealthAdapter;
+        if (adapter?.invocation.kind === 'process')
+            names.add(adapter.invocation.executable);
+    }
+    return [...names].sort();
+}
+/**
+ * Which known worker CLIs are present on `PATH` right now. Presence-only:
+ * never spawns a process and never makes a network call. `registry` and
+ * `pathEnv` are both injectable so callers (and tests) never depend on
+ * whichever CLIs happen to be installed on the running host.
+ */
+export function detectInstalledWorkerClis(options = {}) {
+    const executables = knownWorkerCliExecutables(options.registry);
+    const pathEnv = options.pathEnv ?? process.env.PATH;
+    return executables.filter(executable => executableOnPath(executable, pathEnv));
+}
+/**
+ * Should any setup surface offer or hint turning `worker_dispatch` on?
+ * `false` whenever it is already on, or the offer was previously declined
+ * (`setup.worker_dispatch_offer === 'declined'`) — a user who said no is
+ * not asked again on every run (#3050 item 3). Otherwise `true` once two or
+ * more known worker CLIs are detected.
+ *
+ * `parallelism` and `setup` are deliberately separate parameters, not one
+ * merged config object: `parallelism` is the frozen worker-policy contract
+ * fragment (B-OG-29) and must never gain fields for setup preferences; the
+ * decline itself lives in `setup`, a plain onboarding-preferences block.
+ */
+export function evaluateWorkerDispatchOffer(parallelism, setup, detected) {
+    if (parallelism?.worker_dispatch === true)
+        return { shouldOffer: false, detected };
+    if (setup?.worker_dispatch_offer === 'declined')
+        return { shouldOffer: false, detected };
+    return { shouldOffer: detected.length >= MIN_DETECTED_FOR_OFFER, detected };
+}
+/**
+ * One-line interactive yes/no question naming the detected CLIs. Callers
+ * MUST default the answer to `false` (no) — see #3050's "never enable
+ * without an explicit yes" constraint.
+ */
+export function workerDispatchOfferQuestion(detected) {
+    return `  Detected worker CLIs (${detected.join(', ')}). Enable direct worker dispatch so AIWG `
+        + `can dispatch tasks to them directly, using their own accounts' quota? [y/N]: `;
+}
+/**
+ * One-line non-interactive / regenerate / refresh / doctor hint. Never
+ * prompts and never changes anything by itself — it only names the enable
+ * command and the readiness check that confirms the CLIs are actually
+ * launchable.
+ */
+export function workerDispatchOfferHint(detected) {
+    return `Direct worker dispatch is off; detected worker CLIs: ${detected.join(', ')}. `
+        + `Enable with \`${WORKER_DISPATCH_ENABLE_COMMAND}\` (then check readiness with \`${WORKER_DISPATCH_READINESS_COMMAND}\`).`;
+}
+/**
+ * Accepted values for the `--worker-dispatch` argument (#3062). Only
+ * `aiwg init` and `aiwg setup project` accept this argument directly — it
+ * answers the same question `askWorkerDispatchOffer`/`applyInteractivePrompts`
+ * would otherwise ask interactively, so those two commands can be run
+ * headless without leaving the offer unanswerable.
+ */
+export const WORKER_DISPATCH_ARG_VALUES = ['enable', 'decline'];
+/**
+ * Parse a raw `--worker-dispatch` flag value. `undefined` in means the flag
+ * was not given at all (not an error — the question is still asked/hinted
+ * as before). Any other value that isn't exactly `enable`/`decline` throws,
+ * naming the accepted values; callers should map that to a non-zero exit.
+ *
+ * This is accepted even when fewer than two worker CLIs are detected — an
+ * explicit `--worker-dispatch` choice is honored regardless of the
+ * presence-only CLI detection `evaluateWorkerDispatchOffer` otherwise gates
+ * the interactive question/hint on.
+ */
+export function parseWorkerDispatchArg(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!WORKER_DISPATCH_ARG_VALUES.includes(raw)) {
+        throw new Error(`--worker-dispatch must be one of: ${WORKER_DISPATCH_ARG_VALUES.join(', ')} (got ${JSON.stringify(raw)})`);
+    }
+    return raw;
+}
+/**
+ * Hint variant for the two surfaces (`aiwg init`, `aiwg setup project`) that
+ * accept `--worker-dispatch` directly (#3062): same base hint, plus the
+ * argument itself, so a headless run without a terminal and without the
+ * argument names both the config command and the argument that would have
+ * answered the question directly.
+ */
+export function workerDispatchOfferHintWithArg(detected) {
+    return `${workerDispatchOfferHint(detected)} Or pass --worker-dispatch enable|decline to this command directly.`;
+}
+//# sourceMappingURL=worker-dispatch-offer.js.map

package/dist/src/models/worker-health-readiness.js

@@ -0,0 +1,131 @@
+/** Offline S1 health readiness projection; never launch authority or a probe. */
+import { validateParallelismConfig, resolveWorkerGroupInstallation, workerConfigDigest } from '../config/aiwg-config.js';
+import { assertWorkerHealthQualification } from './provider-policy.js';
+import { resolveWorkerPlan } from './resolver.js';
+import { resolveWorkerEffectiveHealth } from '../serve/worker-invocation.js';
+const repairAction = (code, pointer) => {
+    if (pointer === '/worker/observedAt')
+        return 'refresh-worker-catalog';
+    if (code === 'OG_EFFORT_DENIED')
+        return 'select-qualified-effort';
+    if (code === 'OG_MODEL_UNAPPROVED')
+        return 'review-model-policy-and-freshness';
+    if (code === 'OG_PIN_MISMATCH')
+        return 'review-exact-wrapper-pin';
+    if (code === 'OG_BUDGET_UNMEASURABLE')
+        return 'qualify-budget-enforcement';
+    if (code === 'OG_ADAPTER_UNQUALIFIED')
+        return 'qualify-installation-and-profile';
+    return 'review-worker-configuration';
+};
+export function diagnoseWorkerHealthReadiness(snapshot, request) {
+    const p = snapshot.config.parallelism;
+    const report = { enabled: p?.worker_dispatch === true,
+        ready: true, contextDigest: null, findings: [], thresholds: [] };
+    const add = (finding) => { report.findings.push(finding); };
+    if (!report.enabled) {
+        add({ code: 'WORKER_HEALTH_DISABLED', status: 'info', pointer: '/parallelism/worker_dispatch',
+            message: 'Group dispatch is disabled; legacy execution has no worker health readiness requirement.',
+            nextAction: 'none', role: null });
+        return report;
+    }
+    report.contextDigest = workerConfigDigest({ context: request.context, modelDigests: snapshot.modelDigests });
+    const errors = validateParallelismConfig(p);
+    if (errors.length) {
+        report.ready = false;
+        for (const message of errors)
+            add({ code: 'OG_CONFIG_REFERENCE', status: 'error',
+                pointer: '/parallelism', message, nextAction: 'review-worker-configuration', role: null });
+        return report;
+    }
+    if (p?.worker_mode === 'managed') {
+        add({ code: 'WORKER_HEALTH_MANAGED_DEFERRED', status: 'info', pointer: '/parallelism/worker_mode',
+            message: 'Managed admission and health enforcement are deferred to S2+; this check covers direct readiness.',
+            nextAction: 'use-direct-checkpoint', role: null });
+        return report;
+    }
+    const enabledGroups = Object.values(p?.groups ?? {});
+    const required = new Set(enabledGroups.flatMap(group => group.requiredRoles ?? []));
+    const roles = new Set([...Object.keys(snapshot.models.defaults.workerSelection?.roleGuidance ?? {}), ...required]);
+    if (!roles.size) {
+        report.ready = false;
+        add({ code: 'OG_CONFIG_REFERENCE', status: 'error', pointer: '/defaults/workerSelection/roleGuidance',
+            message: 'No worker role guidance is configured; onboarding cannot offer a qualified route.',
+            nextAction: 'configure-role-guidance', role: null });
+    }
+    const installations = new Set(enabledGroups.flatMap(group => group.members.filter(member => member.enabled !== false).map(member => member.cli)));
+    for (const cli of installations) {
+        if (!p?.clis?.[cli]?.quotaScope)
+            add({ code: 'WORKER_QUOTA_SCOPE_UNKNOWN', status: 'warn', role: null,
+                pointer: `/parallelism/clis/${cli}/quotaScope`,
+                message: 'No explicit quota/account correlation scope; shared aliases cannot establish independent upstream capacity.',
+                nextAction: 'configure-qualified-quota-scope' });
+    }
+    for (const role of roles) {
+        const plan = resolveWorkerPlan(snapshot, { ...request, role: role });
+        const isRequired = required.has(role);
+        const diagnostics = [...plan.diagnostics, ...plan.exclusions.flatMap(item => item.diagnostics)];
+        const seen = new Set();
+        for (const diagnostic of diagnostics) {
+            const key = `${diagnostic.code}:${diagnostic.pointer}:${diagnostic.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            add({ ...diagnostic, status: diagnostic.blocking === false ? 'info' : 'warn', role,
+                nextAction: repairAction(diagnostic.code, diagnostic.pointer) });
+        }
+        if (!plan.selected) {
+            if (isRequired)
+                report.ready = false;
+            add({ code: 'WORKER_ROLE_NOT_READY', status: isRequired ? 'error' : 'warn', role,
+                pointer: `/defaults/workerSelection/roleGuidance/${role}`,
+                message: `${isRequired ? 'Required' : 'Optional'} role has no qualified route; request-time launch remains blocked.`,
+                nextAction: 'qualify-role-route' });
+            continue;
+        }
+        const tuple = plan.selected;
+        try {
+            const { adapter } = resolveWorkerGroupInstallation(p, tuple.cli, snapshot.registry);
+            const profile = adapter.invocationProfiles[tuple.profile];
+            const binding = snapshot.installations[tuple.cli];
+            const model = snapshot.catalog.discovery?.instances?.[tuple.cli]?.models.find(row => row.id === tuple.model || row.apiModelId === tuple.model);
+            assertWorkerHealthQualification(profile, { profileRef: tuple.profile, cliVersion: binding.cliVersion,
+                accountScope: binding.accountScope, inferenceProvider: tuple.inferenceProvider, model: model?.apiModelId ?? tuple.model, effort: tuple.effort });
+            const nativeSteps = profile.controls.stepCap?.support === 'native';
+            if (p?.health?.requireStepCap && !nativeSteps) {
+                if (isRequired)
+                    report.ready = false;
+                add({ code: 'WORKER_STEP_CAP_NOT_READY', status: isRequired ? 'error' : 'warn', role,
+                    pointer: '/parallelism/health/requireStepCap',
+                    message: 'Required step cap lacks native enforcement or qualified runtime pre-step admission evidence.',
+                    nextAction: 'qualify-step-enforcement' });
+                continue;
+            }
+            // External admission needs runtime gate evidence; a config declaration alone cannot prove it.
+            const health = resolveWorkerEffectiveHealth(p?.health, { role, effort: tuple.effort,
+                modelKey: tuple.modelKey, profileRef: tuple.profile, wallSeconds: plan.ceilings.wallSeconds ?? 1800,
+                stepEnforcement: nativeSteps ? 'native' : 'unavailable' });
+            report.thresholds.push({ role, group: tuple.group, member: tuple.member, health });
+            if (!profile.health || profile.health.handshake !== 'semantic' || profile.health.coverage !== 'full') {
+                add({ code: 'WORKER_HEALTH_DEGRADED', status: 'warn', role,
+                    pointer: `/parallelism/clis/${tuple.cli}/invocationProfile`,
+                    message: 'Profile has degraded or unobserved health coverage; progress and stop evidence may be unavailable.',
+                    nextAction: 'qualify-health-signals' });
+            }
+            add({ code: 'WORKER_ROLE_ELIGIBLE', status: 'ok', role,
+                pointer: `/defaults/workerSelection/roleGuidance/${role}`,
+                message: 'Policy route is eligible; launch still requires current installation and task qualification.',
+                nextAction: 'resolve-current-task' });
+        }
+        catch {
+            if (isRequired)
+                report.ready = false;
+            add({ code: 'WORKER_HEALTH_UNQUALIFIED', status: isRequired ? 'error' : 'warn', role,
+                pointer: `/parallelism/clis/${tuple.cli}/invocationProfile`,
+                message: 'Health profile scope or effective settings are invalid; requalify the exact version/account/model/effort.',
+                nextAction: 'qualify-health-signals' });
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=worker-health-readiness.js.map