@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/_lib/subagent_response.ts

@@ -9,6 +9,8 @@
  * Contract: `src/agent-src/contexts/execution/subagent-response-contract.md`.
  */
 
+import { validateAssumption, type CapsuleAssumption } from './subagent_capsule.js';
+
 export type Confidence = 'low' | 'medium' | 'high';
 
 export interface Finding {
@@ -19,12 +21,46 @@ export interface Finding {
     mutating?: boolean;
 }
 
+// ── Committed envelope size caps (road-to-token-economy-dispatch Phase 6.1) ──
+// The envelope is the ONLY return channel: a worker's full result lands on
+// disk (runtime artifact dir, gitignored) and the envelope carries paths +
+// verdict + a BOUNDED summary. Without caps, transcript-shaped output flows
+// back into the orchestrator context and refunds the isolation win — the
+// measured spawn floor is ~251k tokens; a capped envelope is ≤ ~3k. Caps are
+// validator ERRORS, never silent truncation (never-silent discipline): an
+// oversized envelope is rejected loudly and the author shortens it.
+/** Max chars for the summary — bounded prose, not a transcript. */
+export const MAX_SUMMARY_CHARS = 2000;
+/** Max chars for one line-shaped field (handoff, a risk, a finding title). */
+export const MAX_RESPONSE_LINE_CHARS = 240;
+/** Max entries per array (findings, risks, artifact_paths) — mirrors the capsule. */
+export const MAX_RESPONSE_ENTRIES = 40;
+/** Max chars for one artifact path ref. Mirrors the capsule's ref cap. */
+export const MAX_ARTIFACT_REF_CHARS = 200;
+/** Committed max for the WHOLE serialized envelope (~3k tokens ceiling). */
+export const MAX_ENVELOPE_CHARS = 12000;
+
 export interface SubagentResponse {
     summary: string;
     findings: Finding[];
     risks: string[];
     confidence: Confidence;
     handoff: string;
+    /**
+     * Where the worker's FULL results live on disk (runtime artifact dir,
+     * gitignored) — the orchestrator consumes from these paths on demand,
+     * never via wholesale transcript ingestion (Phase 6.1/6.2). Ref tokens
+     * only, capped like every other array.
+     */
+    artifact_paths?: string[];
+    /**
+     * Premises the worker acted on, `{statement, basis, epistemic_state}` —
+     * the same shape and the same validator as the CHECKPOINT capsule
+     * (`subagent_capsule.ts`), so the completed-result and handoff surfaces
+     * cannot drift apart. Optional: absent means not recorded, which is not
+     * the same claim as "no assumptions were made".
+     */
+    assumptions?: CapsuleAssumption[];
 }
 
 const CONFIDENCE: ReadonlySet<string> = new Set<Confidence>(['low', 'medium', 'high']);
@@ -55,6 +91,64 @@ export function validateResponse(input: unknown): ValidationResult {
             }
         }
     }
+    if (r.assumptions !== undefined) {
+        if (!Array.isArray(r.assumptions)) {
+            errors.push('assumptions must be an array of {statement, basis, epistemic_state}');
+        } else {
+            for (const [i, a] of (r.assumptions as unknown[]).entries()) {
+                errors.push(...validateAssumption(a, `assumptions[${i}]`));
+            }
+        }
+    }
+    // ── Committed size caps (Phase 6.1) — errors, never silent truncation ──
+    if (typeof r.summary === 'string' && r.summary.length > MAX_SUMMARY_CHARS) {
+        errors.push(`summary is ${r.summary.length} chars (max ${MAX_SUMMARY_CHARS}) — the envelope carries a bounded summary; the full result belongs on disk (artifact_paths)`);
+    }
+    if (typeof r.handoff === 'string' && r.handoff.length > MAX_RESPONSE_LINE_CHARS) {
+        errors.push(`handoff is ${r.handoff.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+    }
+    for (const [key, arr] of [
+        ['findings', r.findings],
+        ['risks', r.risks],
+        ['artifact_paths', r.artifact_paths],
+    ] as const) {
+        if (Array.isArray(arr) && arr.length > MAX_RESPONSE_ENTRIES) {
+            errors.push(`${key} carries ${arr.length} entries (max ${MAX_RESPONSE_ENTRIES}) — an envelope is a handoff, not a transcript`);
+        }
+    }
+    if (Array.isArray(r.risks)) {
+        for (const [i, risk] of (r.risks as unknown[]).entries()) {
+            if (typeof risk === 'string' && risk.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`risks[${i}] is ${risk.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (Array.isArray(r.findings)) {
+        for (const [i, f] of (r.findings as Finding[]).entries()) {
+            if (f && typeof f.title === 'string' && f.title.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`finding[${i}] title is ${f.title.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (r.artifact_paths !== undefined) {
+        if (!Array.isArray(r.artifact_paths)) {
+            errors.push('artifact_paths must be an array of path ref tokens');
+        } else {
+            for (const [i, p] of (r.artifact_paths as unknown[]).entries()) {
+                if (typeof p !== 'string' || p.includes('\n') || p.length > MAX_ARTIFACT_REF_CHARS) {
+                    errors.push(`artifact_paths[${i}] must be a single-line path ref ≤ ${MAX_ARTIFACT_REF_CHARS} chars`);
+                }
+            }
+        }
+    }
+    try {
+        const serialized = JSON.stringify(input);
+        if (serialized.length > MAX_ENVELOPE_CHARS) {
+            errors.push(`envelope serializes to ${serialized.length} chars (max ${MAX_ENVELOPE_CHARS}) — move content to disk and reference it via artifact_paths`);
+        }
+    } catch {
+        errors.push('envelope is not JSON-serializable');
+    }
     return { valid: errors.length === 0, errors };
 }
 

package/src/scripts/_lib/subagent_spawn.ts

@@ -13,6 +13,8 @@
 
 import * as crypto from 'node:crypto';
 
+import { CAPSULE_WATERMARK_FRACTION } from './worker_budget.js';
+
 export type RoleMode = 'developer' | 'reviewer' | 'tester' | 'po' | 'incident' | 'planner';
 
 const ROLE_MODES: ReadonlySet<string> = new Set<RoleMode>([
@@ -55,6 +57,12 @@ export interface SpawnBrief {
     knowledge_refs: string[];
     /** Per-worker token stop-loss; null = unset (legacy dispatch). */
     max_tokens_per_worker: number | null;
+    /**
+     * Token count at which the worker emits a CHECKPOINT capsule — DERIVED from
+     * `max_tokens_per_worker`, never set independently, so the watermark cannot
+     * drift away from the budget it sits under. Null when no budget is set.
+     */
+    capsule_watermark: number | null;
     warnings: string[];
 }
 
@@ -112,6 +120,10 @@ export function composeSpawnBrief(sel: SpawnSelection): SpawnBrief {
         personas,
         knowledge_refs,
         max_tokens_per_worker,
+        capsule_watermark:
+            max_tokens_per_worker === null
+                ? null
+                : Math.floor(max_tokens_per_worker * CAPSULE_WATERMARK_FRACTION),
         warnings,
     };
 }
@@ -133,6 +145,7 @@ export function serializeSpawnPayload(brief: SpawnBrief): string {
         profile: brief.profile,
         personas: brief.personas,
         max_tokens_per_worker: brief.max_tokens_per_worker,
+        capsule_watermark: brief.capsule_watermark,
     });
     const variableTail = JSON.stringify({
         task: brief.task,

package/src/scripts/_lib/subagent_steering.ts

@@ -26,14 +26,19 @@ export const GUARDRAILS = {
     user_override_rate: 0.3,
 } as const;
 
+/**
+ * Always-on orchestration (road-to-always-on-orchestration Phase 1) removed
+ * the `enabled`/`auto` settings this state used to carry — the only
+ * surviving switch is the audited incident halt.
+ */
 export interface LayerState {
-    enabled: boolean;
-    auto: 'off' | 'ask' | 'on';
+    /** `emergency.orchestration_halt`. */
+    halted: boolean;
 }
 
-/** The kill-switch: layer is disabled when the master switch is off or auto is off. */
+/** The kill-switch: layer is disabled only during an active emergency halt. */
 export function isLayerDisabled(state: LayerState): boolean {
-    return !state.enabled || state.auto === 'off';
+    return state.halted;
 }
 
 /** N=3 per-target budget: halt once consecutive failed attempts reach the cap. */

package/src/scripts/_lib/tier_budget_routing.ts

@@ -43,7 +43,12 @@ export interface PickTierInputs {
     adequate_tier: BudgetTier;
     /** Per-tier budget state, complete over TIER_ORDER. */
     budgets: Record<BudgetTier, TierBudgetState>;
-    /** subagents.budget_routing setting. */
+    /**
+     * Caller-supplied switch. Formerly sourced from the `subagents.budget_routing`
+     * settings key, deleted by always-on orchestration (Phase 1) — this
+     * function has no production caller today, so the field stays as the
+     * DESIGNED input shape; a future wiring supplies its own source.
+     */
     routing_switch: BudgetRoutingSwitch;
     /** Estimated cost of the dispatch (USD) for the availability check. */
     estimated_cost_usd: number;

package/src/scripts/_lib/worker_budget.ts

@@ -35,6 +35,24 @@ export function budgetForTier(tier: Tier, sessionTier: Exclude<Tier, 'inherit'>
     return MAX_TOKENS_PER_WORKER[effective];
 }
 
+/**
+ * Fraction of the stop-loss budget at which a worker emits its CHECKPOINT
+ * capsule (road-to-worker-generation-recycling, Phase 1).
+ *
+ * The headroom IS the mechanism: a worker at 100 % of its budget cannot
+ * summarise itself, so the watermark sits below the kill line rather than on
+ * it. A start value, not a tuned one — Phase 1 measures it in shadow against a
+ * second trigger arm before anything acts on it, and `blocker:
+ * capsule-quality-near-budget` exists because a bad watermark and a bad
+ * mechanism look identical from one sample.
+ */
+export const CAPSULE_WATERMARK_FRACTION = 0.8;
+
+/** Token count at which a worker of this tier emits its capsule. */
+export function watermarkForTier(tier: Tier, sessionTier: Exclude<Tier, 'inherit'> = 'high'): number {
+    return Math.floor(budgetForTier(tier, sessionTier) * CAPSULE_WATERMARK_FRACTION);
+}
+
 /** Where the orchestrator should send the task after a budget hit. */
 export type NextRung = 'primitive' | 'higher-tier-subagent' | 'in-session';
 
@@ -64,19 +82,36 @@ export interface BudgetEvaluation {
     budget_hit: boolean;
     consumed: number;
     budget: number;
+    /** Token count at which the CHECKPOINT capsule is due (below the kill line). */
+    watermark: number;
+    /** Consumption reached the watermark but not yet the stop-loss. */
+    watermark_hit: boolean;
     reason: string;
 }
 
-/** Evaluate consumption against the worker's budget. */
+/**
+ * Evaluate consumption against the worker's budget.
+ *
+ * Two lines, not one: the **watermark** (emit a capsule, still working) and the
+ * **stop-loss** (return a partial result, stop). A budget hit implies the
+ * watermark was passed, so `watermark_hit` marks the band BETWEEN them — the
+ * only window in which a capsule can still be written.
+ */
 export function evaluateWorkerBudget(consumed: number, budget: number): BudgetEvaluation {
     const hit = consumed >= budget;
+    const watermark = Math.floor(budget * CAPSULE_WATERMARK_FRACTION);
+    const watermarkHit = !hit && consumed >= watermark;
     return {
         budget_hit: hit,
         consumed,
         budget,
+        watermark,
+        watermark_hit: watermarkHit,
         reason: hit
             ? `budget hit (${consumed} >= ${budget}) — return partial result + escalation flag, stop exploring`
-            : `within budget (${consumed} < ${budget})`,
+            : watermarkHit
+              ? `watermark reached (${consumed} >= ${watermark}) — emit a CHECKPOINT capsule while there is headroom to write one`
+              : `within budget (${consumed} < ${budget})`,
     };
 }
 

package/src/scripts/ai_council/clients.ts

@@ -45,6 +45,37 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { SESSION_ROLE_ENV } from '../_lib/session_role.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+
+// Session-wide subagent model ceiling (token-economy-dispatch Phase 5.2):
+// class-C setting, default absent, HUMAN-set only. When present, the CLI
+// spawn below exports CLAUDE_CODE_SUBAGENT_MODEL so the spawned vendor
+// session caps its own subagents' models. Memoised PER CWD, not per
+// process (review finding 2026-08-10): a long-lived server process may
+// serve several projects, and a single-slot memo would apply project A's
+// spend cap to project B's spawns. A human edit still needs a process
+// restart to be seen — acceptable for a per-install cap, stated here.
+const _modelCeilingMemo = new Map<string, string | null>();
+export function _subagentModelCeiling(cwd: string = process.cwd()): string | null {
+    const hit = _modelCeilingMemo.get(cwd);
+    if (hit !== undefined) return hit;
+    let ceiling: string | null;
+    try {
+        const settings = load_agent_settings({ cwd }) as Record<string, unknown>;
+        const sub = (settings['subagents'] ?? {}) as Record<string, unknown>;
+        const v = typeof sub['model_ceiling'] === 'string' ? sub['model_ceiling'].trim() : '';
+        ceiling = v.length > 0 ? v : null;
+    } catch {
+        ceiling = null; // unreadable settings → no ceiling (fail-open)
+    }
+    _modelCeilingMemo.set(cwd, ceiling);
+    return ceiling;
+}
+/** Test seam: reset the per-cwd ceiling memo. */
+export function _resetModelCeilingMemo(): void {
+    _modelCeilingMemo.clear();
+}
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import { appendEvent } from './events_log.js';
 
@@ -1052,9 +1083,12 @@ export class SubprocessError extends Error {
  * `~/.event4u/agent-config/cli-calls.json` and resets on UTC date rollover.
  *
  * Subclass contract:
- * - `name`: provider key (`anthropic`, `openai`, `gemini`, …).
- * - `default_binary`: executable name resolved via PATH when the member-level
- *   `binary:` field is not set.
+ * - `super(opts, { name, default_binary })`: `name` is the provider key
+ *   (`anthropic`, `openai`, `gemini`, …); `default_binary` is the executable
+ *   resolved via PATH when the member-level `binary:` field is not set. Both
+ *   are passed explicitly to `super()` — not read off subclass instance
+ *   fields — because a subclass's own field initializers run only AFTER this
+ *   `super()` call returns.
  * - `_build_command(system_prompt, user_prompt, max_tokens)`: return the argv.
  * - `_parse_output(stdout, stderr)`: return a partial `CouncilResponse`.
  *
@@ -1097,8 +1131,22 @@ export abstract class CliClient extends ExternalAIClient {
         'usage limit',
     ];
 
-    constructor(opts: CliClientOptions & { model: string }) {
+    /**
+     * `identity` carries the subclass constants (`name`, `default_binary`)
+     * that construction validates against. They are passed explicitly rather
+     * than read off `this.name` / `this.default_binary` because subclass
+     * instance-field initializers (`override default_binary = 'claude'`,
+     * declared in the subclass body) run only AFTER this `super()` call
+     * returns — reading them here, before that happens, would always see the
+     * base class's own field defaults (`''`), not the subclass override.
+     */
+    constructor(
+        opts: CliClientOptions & { model: string },
+        identity: { name: string; default_binary: string },
+    ) {
         super();
+        this.name = identity.name;
+        this.default_binary = identity.default_binary;
         this.model = opts.model;
         this.timeout_seconds = opts.timeout_seconds ?? DEFAULT_CLI_TIMEOUT_SECONDS;
         this.max_calls_per_day = opts.max_calls_per_day ?? null;
@@ -1162,7 +1210,25 @@ export abstract class CliClient extends ExternalAIClient {
             // (loader preload, git *_COMMAND, NODE_OPTIONS, …) so an
             // attacker-influenced parent env cannot RCE via the spawned CLI
             // or a `git` it invokes internally.
-            env: hardenedSpawnEnv(),
+            // Role marking (token-economy-dispatch Phase 2.2): a council
+            // member CLI session is worker-class — it never talks to OUR
+            // user, never dispatches sub-workers, never runs a council.
+            // The spawned vendor CLI loads this repo's hook chains; the
+            // marker lets the dispatcher run the thinner worker chain
+            // (manifest `roles.worker.drop`; pre_tool_use guards are
+            // structurally exempt). This is the ONE in-tree spawn point
+            // that launches a separate CLI session today — Agent-tool
+            // subagents share the host process env and cannot be marked
+            // (probed live 2026-08-10; see _lib/session_role.ts).
+            // The optional model ceiling (subagents.model_ceiling, class C)
+            // rides the same spawn: a spend cap the human set per install.
+            env: hardenedSpawnEnv({
+                [SESSION_ROLE_ENV]: 'worker',
+                ...((): Record<string, string> => {
+                    const ceiling = _subagentModelCeiling();
+                    return ceiling !== null ? { CLAUDE_CODE_SUBAGENT_MODEL: ceiling } : {};
+                })(),
+            }),
         };
         if (stdinPayload !== null) {
             spawnOpts.input = stdinPayload;
@@ -1353,19 +1419,20 @@ export abstract class CliClient extends ExternalAIClient {
  * collides with argv length limits.
  */
 export class AnthropicCliClient extends CliClient {
-    override name = 'anthropic';
-    override default_binary = 'claude';
     override subscription_label = 'claude-pro';
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'anthropic', default_binary: 'claude' },
+        );
     }
 
     protected override _build_command(
@@ -1446,8 +1513,6 @@ export class AnthropicCliClient extends CliClient {
  * token usage in `usage.input_tokens` / `usage.output_tokens`.
  */
 export class OpenAICliClient extends CliClient {
-    override name = 'openai';
-    override default_binary = 'codex';
     override subscription_label = 'chatgpt-plus';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1458,14 +1523,17 @@ export class OpenAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'openai', default_binary: 'codex' },
+        );
     }
 
     protected override _build_command(
@@ -1569,8 +1637,6 @@ export class OpenAICliClient extends CliClient {
  * stdin to dodge argv limits.
  */
 export class GeminiCliClient extends CliClient {
-    override name = 'gemini';
-    override default_binary = 'gemini';
     override subscription_label = 'gemini-pro';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1581,14 +1647,17 @@ export class GeminiCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'gemini', default_binary: 'gemini' },
+        );
     }
 
     protected override _build_command(
@@ -1686,8 +1755,6 @@ export class GeminiCliClient extends CliClient {
  * heuristically (chars / 4) for the audit-trail.
  */
 export class XAICliClient extends CliClient {
-    override name = 'xai';
-    override default_binary = 'grok';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1698,14 +1765,17 @@ export class XAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_XAI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_XAI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'xai', default_binary: 'grok' },
+        );
     }
 
     protected override _build_command(
@@ -1752,8 +1822,6 @@ export class XAICliClient extends CliClient {
  * Invokes `perplexity -p <prompt>`. Output is plain text — no JSON envelope.
  */
 export class PerplexityCliClient extends CliClient {
-    override name = 'perplexity';
-    override default_binary = 'perplexity';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1764,14 +1832,17 @@ export class PerplexityCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'perplexity', default_binary: 'perplexity' },
+        );
     }
 
     protected override _build_command(