@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/_lib/agent_settings.ts

@@ -762,9 +762,67 @@ export function load_agent_settings(
             _deep_merge(merged, layer);
         }
     }
+    _warn_removed_always_on_keys(merged);
     return merged;
 }
 
+/**
+ * Settings keys deleted by the always-on-orchestration doctrine
+ * (road-to-always-on-orchestration Phase 1 for the `subagents.*` keys;
+ * Phase 1 Step 1.3 for `ai_team.enabled`). A leftover value from an older
+ * install is ignored — never applied by any reader — and surfaced with ONE
+ * deprecation line per key per process run (stderr; the exit code never
+ * changes).
+ *
+ * `ai_team.enabled` joined this list in Step 1.3: the `/team` family's
+ * availability is now a codex-CLI/auth FACT
+ * (`src/scripts/ai_team/availability.ts`), the same doctrine already
+ * applied to `subagents.*` below, not a settings flag. The `ai_team`
+ * config loader (`src/scripts/ai_team/config.ts`) separately accepts a
+ * leftover `enabled` key without failing closed, so this warning is the
+ * only surfaced signal of the deletion.
+ */
+const REMOVED_ALWAYS_ON_KEYS: readonly string[] = [
+    'subagents.enabled',
+    'subagents.auto',
+    'subagents.host_capabilities',
+    'subagents.budget_routing',
+    'ai_team.enabled',
+];
+
+/** Keys already warned about in THIS process — the "once per run" dedupe. */
+const _warnedRemovedAlwaysOnKeys = new Set<string>();
+
+/** Read one dotted path out of a merged settings tree; `undefined` when absent. */
+function _readDottedSettingsPath(root: SettingsDict, dotted: string): SettingsValue {
+    let node: SettingsValue = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+            return undefined;
+        }
+        node = (node as SettingsDict)[part];
+    }
+    return node;
+}
+
+/**
+ * Warn once per process, on stderr, for every {@link REMOVED_ALWAYS_ON_KEYS}
+ * still present in a resolved settings tree. Never throws, never changes
+ * what the caller does with `merged` — a pure notification side effect.
+ */
+function _warn_removed_always_on_keys(merged: SettingsDict): void {
+    for (const key of REMOVED_ALWAYS_ON_KEYS) {
+        if (_warnedRemovedAlwaysOnKeys.has(key)) {
+            continue;
+        }
+        if (_readDottedSettingsPath(merged, key) === undefined) {
+            continue;
+        }
+        _warnedRemovedAlwaysOnKeys.add(key);
+        process.stderr.write(`${key} was removed (always-on orchestration); ignored.\n`);
+    }
+}
+
 /**
  * Return the merged `modules:` configuration with defaults applied.
  *

package/src/scripts/_lib/auto_dispatch.corpus.test.ts

@@ -23,7 +23,7 @@ import {
     type TaskSignals,
 } from './auto_dispatch.js';
 
-const ON: ActivationInputs = { enabled: true, auto: 'on', subagent_spawn: true };
+const ON: ActivationInputs = { halted: false, subagent_spawn: true };
 
 /** Corpus signals transcribed from each task's documented "Classification signal". */
 const CORPUS: Array<{

package/src/scripts/_lib/auto_dispatch.ts

@@ -7,19 +7,24 @@
  * Decides whether a task is delegable to subagents and which
  * `subagent-orchestration` mode fits — with NO per-turn LLM meta-call.
  *
+ * Always-on orchestration (road-to-always-on-orchestration Phase 1): there is
+ * no more `subagents.enabled` / `subagents.auto` setting gating this. The
+ * layer activates on any host reporting a subagent primitive, unless the one
+ * audited incident switch (`emergency.orchestration_halt`) is set.
+ *
  * Contract highlights:
  * - A task is delegable only on an enumerated structural signal.
  * - Trivial tasks below the size floor never delegate.
- * - Ambiguity → `ask` (when `auto == 'ask'`) or in-session, never speculative
- *   spawn.
- * - The activation gate (`enabled`, `auto != off`, `subagent_spawn`) runs
- *   first; any failure short-circuits to in-session.
+ * - A matched signal always DISPATCHES (there is no more ask-before-dispatch
+ *   mode); an AMBIGUOUS verdict (no enumerated signal matched) is always an
+ *   `ask` VERDICT to the user, never a speculative spawn.
+ * - The activation gate (`halted`, `subagent_spawn`) runs first; any failure
+ *   short-circuits to in-session.
  */
 
 /** Minimum task-size estimate (exclusive) below which a task never delegates. */
 export const SIZE_FLOOR = 1;
 
-export type AutoMode = 'off' | 'ask' | 'on';
 export type DispatchMode = 'do-in-steps' | 'do-in-parallel';
 export type DispatchAction = 'dispatch' | 'ask' | 'in-session';
 
@@ -35,10 +40,14 @@ export interface TaskSignals {
     size_estimate: number;
 }
 
-/** Activation inputs resolved from settings + the host-capability manifest. */
+/**
+ * Activation inputs resolved from the emergency incident switch + the
+ * host-capability manifest. No `enabled`/`auto` fields — always-on
+ * orchestration carries no per-layer setting to resolve them from.
+ */
 export interface ActivationInputs {
-    enabled: boolean;
-    auto: AutoMode;
+    /** `emergency.orchestration_halt` — the one audited incident switch. */
+    halted: boolean;
     subagent_spawn: boolean;
 }
 
@@ -59,8 +68,7 @@ function inSession(reason: string): Classification {
  */
 export function classifyTask(signals: TaskSignals, activation: ActivationInputs): Classification {
     // ── Activation gate — any failure short-circuits to in-session ──
-    if (!activation.enabled) return inSession('subagents.enabled is false');
-    if (activation.auto === 'off') return inSession('subagents.auto is off');
+    if (activation.halted) return inSession('emergency.orchestration_halt is set');
     if (!activation.subagent_spawn) return inSession('host has no subagent_spawn primitive');
 
     // ── Size floor — trivial tasks never delegate ──
@@ -82,16 +90,13 @@ export function classifyTask(signals: TaskSignals, activation: ActivationInputs)
     }
 
     if (mode === null) {
-        // No enumerated signal matched → ambiguous. Ask under `ask`, else in-session.
-        if (activation.auto === 'ask') {
-            return { delegable: false, action: 'ask', mode: null, reason: 'no delegable signal — borderline, ask' };
-        }
-        return inSession('no enumerated delegable signal matched');
+        // No enumerated signal matched → ambiguous. Always an `ask` VERDICT —
+        // there is no more setting under which this silently stays in-session.
+        return { delegable: false, action: 'ask', mode: null, reason: 'no delegable signal — borderline, ask' };
     }
 
-    // Matched a signal. Dispatch under `on`, ask under `ask`.
-    const action: DispatchAction = activation.auto === 'on' ? 'dispatch' : 'ask';
-    return { delegable: true, action, mode, reason };
+    // Matched a signal → always dispatch (always-on: no ask-before-dispatch mode).
+    return { delegable: true, action: 'dispatch', mode, reason };
 }
 
 // ── Lookup-class routing (L0 — road-to-lean-agent-init) ──

package/src/scripts/_lib/capsule_trigger.ts

@@ -0,0 +1,124 @@
+/**
+ * Capsule-emission triggers — the two arms Phase 1 compares in shadow
+ * (road-to-worker-generation-recycling).
+ *
+ * Pure, no-I/O. Two candidate answers to "when should a worker hand off?":
+ *
+ *   - **watermark** — cumulative tokens reach `CAPSULE_WATERMARK_FRACTION` of
+ *     the stop-loss budget (`worker_budget.ts`). Cheap, already instrumented,
+ *     and indifferent to whether the worker is still learning anything.
+ *   - **saturation** — novelty per step, by term frequency, falls below a
+ *     threshold. The hypothesis it encodes: a worker near its budget should
+ *     have stopped EARLIER, not summarised harder — a worker that has stopped
+ *     surfacing new terms is done discovering regardless of its token count.
+ *
+ * Deliberately term-frequency only. Embeddings would add a model dependency,
+ * a similarity threshold nobody can defend, and a second thing to explain when
+ * the arm loses — and the arm has to be able to lose cheaply for the shadow
+ * comparison to mean anything.
+ *
+ * NOTHING ACTS ON THESE. Phase 1 logs the step at which each trigger WOULD have
+ * fired and the worker runs to stop-loss exactly as before, so the measurement
+ * is not confounded by the mechanism it is measuring.
+ */
+
+import { CAPSULE_WATERMARK_FRACTION } from './worker_budget.js';
+
+/** Trailing steps averaged before saturation can fire. */
+export const SATURATION_WINDOW = 3;
+/** Mean novelty below this over the window = saturated. */
+export const SATURATION_THRESHOLD = 0.2;
+
+/** One observed worker step. `terms` is whatever the step surfaced — paths, symbols, words. */
+export interface StepObservation {
+    /** Tokens this step consumed (per-step, not cumulative). */
+    tokens: number;
+    /** Terms surfaced by this step. Normalised and deduped internally. */
+    terms: string[];
+}
+
+export interface TriggerComparison {
+    /** Steps observed. */
+    steps: number;
+    /** 1-based step at which the token watermark was crossed; null = never. */
+    watermark_step: number | null;
+    /** 1-based step at which novelty saturated; null = never. */
+    saturation_step: number | null;
+    /** Per-step novelty ratio (new terms / distinct terms in that step). */
+    novelty: number[];
+    /** Cumulative tokens after each step. */
+    cumulative_tokens: number[];
+}
+
+/** Lowercase, strip surrounding punctuation. No stemming — a stemmer is a second thing to defend. */
+function normalise(term: string): string {
+    return term.toLowerCase().replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '');
+}
+
+function distinctTerms(terms: string[]): Set<string> {
+    const out = new Set<string>();
+    for (const raw of terms) {
+        if (typeof raw !== 'string') continue;
+        const t = normalise(raw);
+        if (t.length > 0) out.add(t);
+    }
+    return out;
+}
+
+/**
+ * Run both arms over an observed step sequence and report where each WOULD
+ * have fired. Both may be null (neither fired) — which is a publishable result,
+ * not a failure of the instrument.
+ */
+export function compareTriggers(steps: StepObservation[], budget: number): TriggerComparison {
+    const watermark = Math.floor(budget * CAPSULE_WATERMARK_FRACTION);
+    const seen = new Set<string>();
+    const novelty: number[] = [];
+    const cumulative_tokens: number[] = [];
+    let cumulative = 0;
+    let watermark_step: number | null = null;
+    let saturation_step: number | null = null;
+
+    for (const [i, step] of steps.entries()) {
+        cumulative += Number.isFinite(step.tokens) ? step.tokens : 0;
+        cumulative_tokens.push(cumulative);
+        if (watermark_step === null && budget > 0 && cumulative >= watermark) {
+            watermark_step = i + 1;
+        }
+
+        const terms = distinctTerms(step.terms ?? []);
+        let fresh = 0;
+        for (const t of terms) {
+            if (!seen.has(t)) {
+                fresh += 1;
+                seen.add(t);
+            }
+        }
+        // A step that surfaced nothing is fully saturated by definition: it
+        // learned nothing. Scoring it as 1.0 ("all new") would let an idle
+        // worker look maximally productive.
+        novelty.push(terms.size === 0 ? 0 : fresh / terms.size);
+
+        if (saturation_step === null && novelty.length >= SATURATION_WINDOW) {
+            const window = novelty.slice(-SATURATION_WINDOW);
+            const mean = window.reduce((a, b) => a + b, 0) / window.length;
+            if (mean < SATURATION_THRESHOLD) saturation_step = i + 1;
+        }
+    }
+
+    return { steps: steps.length, watermark_step, saturation_step, novelty, cumulative_tokens };
+}
+
+/**
+ * Which arm fired first, for the paired comparison in `docs/CLAIMS.md`
+ * (`worker-capsule-trigger-arm`). `null` = neither fired; `'tie'` = same step.
+ */
+export function earlierArm(c: TriggerComparison): 'watermark' | 'saturation' | 'tie' | null {
+    const w = c.watermark_step;
+    const s = c.saturation_step;
+    if (w === null && s === null) return null;
+    if (w === null) return 'saturation';
+    if (s === null) return 'watermark';
+    if (w === s) return 'tie';
+    return w < s ? 'watermark' : 'saturation';
+}

package/src/scripts/_lib/host_capability.ts

@@ -1,9 +1,9 @@
 /**
  * Host-capability manifest normalizer + committed capability registry.
  *
- * Pure, no-I/O helper that takes a partial / unknown object (typically the
- * `subagents.host_capabilities` override from `.agent-settings.yml`, or the
- * agent's own host-knowledge object) and returns a fully-populated manifest.
+ * Pure, no-I/O helper that takes a partial / unknown object (an explicit
+ * caller-supplied override, or the agent's own host-knowledge object) and
+ * returns a fully-populated manifest.
  *
  * Contract — see `src/agent-src/contexts/execution/host-capability-manifest.md`:
  *
@@ -16,14 +16,23 @@
  * adds a resolution order in front of the safe default so a fresh install on
  * a KNOWN host does not ship delegation dead by default:
  *
- *   explicit `subagents.host_capabilities` override (wins, whole-object,
- *   unchanged semantics) → committed registry row for the detected host
- *   (`HOST_CAPABILITY_REGISTRY`) → `SAFE_DEFAULT` (all false).
+ *   explicit override (wins, whole-object, unchanged semantics) → committed
+ *   registry row for the detected host (`HOST_CAPABILITY_REGISTRY`) →
+ *   `SAFE_DEFAULT` (all false).
  *
  * The registry lists only OBSERVED capabilities for a host this repo has
  * actually measured (see the roadmap's transcript evidence) — never a
  * speculative entry for a host nobody has verified.
+ *
+ * `probeHostCapabilities` (road-to-always-on-orchestration Phase 1) is the
+ * production entry point as of this change: capability is a FACT about the
+ * host, never a settings decision, so the former `subagents.host_capabilities`
+ * settings override was deleted. `resolveHostCapabilities`'s `override`
+ * parameter stays for back-compat (tests, and any caller that genuinely has a
+ * host-knowledge object of its own) — no production caller passes a
+ * settings-derived value into it any more.
  */
+import process from 'node:process';
 
 /** Resolved host-capability manifest. All booleans, `schema_version` fixed at 1. */
 export interface HostCapabilityManifest {
@@ -32,6 +41,27 @@ export interface HostCapabilityManifest {
     parallel_spawn: boolean;
     status_polling: boolean;
     separate_quota_pool: boolean;
+    /**
+     * Claude Code's experimental multi-instance Agent Teams primitive
+     * (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`). Resolved ONLY by
+     * {@link probeHostCapabilities}'s live environment probe — the registry
+     * and `normalizeHostManifest` never infer it from a host id, because
+     * this repo has not observed the flag's shape on any host, only its
+     * documented existence.
+     */
+    agent_teams: boolean;
+    /**
+     * The host can kill a running worker and spawn a fresh one that continues
+     * the SAME task mid-flight — the primitive worker-generation recycling
+     * needs (road-to-worker-generation-recycling, `blocker: host-worker-respawn`).
+     *
+     * `false` on every host today, deliberately: like `status_polling` and
+     * `separate_quota_pool`, this field is set `true` only once the capability
+     * is OBSERVED on a host, never by inference from the fact that spawning and
+     * killing both exist separately. A host without it degrades to today's
+     * stop-loss behaviour — loudly, never silently.
+     */
+    worker_respawn: boolean;
 }
 
 /** Safe default — unknown host assumes no subagent primitive. */
@@ -41,6 +71,8 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     parallel_spawn: false,
     status_polling: false,
     separate_quota_pool: false,
+    agent_teams: false,
+    worker_respawn: false,
 };
 
 /** Coerce one field: only a strict boolean `true` survives; everything else is `false`. */
@@ -67,6 +99,8 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         parallel_spawn: asBool(src.parallel_spawn),
         status_polling: asBool(src.status_polling),
         separate_quota_pool: asBool(src.separate_quota_pool),
+        agent_teams: asBool(src.agent_teams),
+        worker_respawn: asBool(src.worker_respawn),
     };
 }
 
@@ -140,3 +174,26 @@ export function resolveHostCapabilities(
     }
     return { ...SAFE_DEFAULT, ...row, schema_version: 1 };
 }
+
+/**
+ * Probe the effective host-capability manifest for `hostId` from OBSERVABLE
+ * FACTS ONLY (road-to-always-on-orchestration Phase 1) — the committed
+ * registry row for the host, merged with a live environment probe. This is
+ * the production entry point: capability is a fact about the host, never a
+ * settings decision, so there is no override parameter here (that stays on
+ * {@link resolveHostCapabilities} for back-compat callers only).
+ *
+ * The one probed fact today: `agent_teams` resolves `true` when
+ * `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set (any non-empty value) in the
+ * process environment — the one host fact this repo can observe about Claude
+ * Code's documented-but-unshipped-by-default multi-instance Agent Teams
+ * primitive. A registry row can also carry `agent_teams: true` directly for a
+ * host where it is unconditionally available; the two sources OR together —
+ * a probe never turns a registry-granted capability back off.
+ */
+export function probeHostCapabilities(hostId: string | null | undefined): HostCapabilityManifest {
+    const base = resolveHostCapabilities(hostId);
+    const flag = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    const probedAgentTeams = typeof flag === 'string' && flag !== '';
+    return { ...base, agent_teams: base.agent_teams || probedAgentTeams };
+}