@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/_lib/user_global_revocations.ts

@@ -0,0 +1,110 @@
+/**
+ * The user-memory revocation ledger — Phase 4 of road-to-global-user-memory
+ * ("delete, revoke, audit").
+ *
+ * Reuses ADR-121's `.revocations.jsonl` tombstone-before-deletion pattern
+ * from `knowledge_global_promote.ts` (`append_tombstone` / `load_tombstones`)
+ * VERBATIM at the mechanism level: same filename, same single
+ * `fs.appendFileSync` per entry (never rewritten), same "the caller MUST
+ * call this BEFORE deleting the thing it documents" contract, same tolerant
+ * reader (a malformed line is skipped, never crashes the read), same
+ * per-domain ledger (this one lives under the `user/` root, exactly as
+ * ADR-121's lives under the knowledge store's own root — no line from one
+ * ledger is ever readable as a line of the other).
+ *
+ * The one adaptation ADR-121's shape cannot express unchanged: its
+ * `RevocationEntry.card_id` names a knowledge CARD, addressed by a stable,
+ * content-derived slug (`card_id_from`). Neither a buffered observation nor
+ * a `profile.md` field has an analogous natural id — the Phase 2/3 JSONL
+ * schema never added one, and a profile field is a YAML key, not a file
+ * with a stem. This module's entries therefore use `entity_id` in place of
+ * `card_id` — the generic name reflects that two different callers
+ * (`user_global_observations.ts`'s per-observation delete/purge,
+ * `agent_user_profile.ts`'s per-field revoke) share this ONE ledger rather
+ * than each inventing its own. Field order, the `{revoked_at, <id>, reason}`
+ * shape, and every operational guarantee are otherwise unchanged.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as user_global_paths from './user_global_paths.js';
+
+/** Relative-to-root path of the ledger — lives beside the profile/buffer it audits. */
+export const REVOCATIONS_RELATIVE = path.join('user', '.revocations.jsonl');
+
+/** One append-only tombstone line: what was revoked, when, and why. */
+export interface RevocationEntry {
+    readonly revoked_at: string;
+    readonly entity_id: string;
+    readonly reason: string;
+}
+
+function _writeTarget(env: user_global_paths.EnvMap | null): string {
+    return user_global_paths.write_target(REVOCATIONS_RELATIVE, { env });
+}
+
+/**
+ * Append one tombstone line to the revocation ledger — the caller MUST call
+ * this BEFORE deleting the observation/field it documents. Append-only (a
+ * single `fs.appendFileSync`, never rewritten): no delete or purge call
+ * ever removes a prior tombstone, so the ledger stays a durable audit trail
+ * across every deletion path — mirroring `knowledge_global_promote.ts`'s
+ * `append_tombstone` exactly.
+ */
+export function appendTombstone(
+    entity_id: string,
+    reason: string,
+    options: { today?: string | undefined; env?: user_global_paths.EnvMap | null } = {},
+): RevocationEntry {
+    const entry: RevocationEntry = {
+        revoked_at: options.today ?? new Date().toISOString().slice(0, 10),
+        entity_id,
+        reason: reason || 'no reason given',
+    };
+    const target = _writeTarget(options.env ?? null);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, JSON.stringify(entry) + '\n', 'utf-8');
+    return entry;
+}
+
+/** Read the revocation ledger. Tolerant: missing file → []; malformed lines are skipped. */
+export function loadTombstones(env?: user_global_paths.EnvMap | null): RevocationEntry[] {
+    const resolved = user_global_paths.resolve_with_fallback(REVOCATIONS_RELATIVE, {
+        env: env ?? null,
+    });
+    if (resolved === null) {
+        return [];
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(resolved, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: RevocationEntry[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.trim();
+        if (!line) {
+            continue;
+        }
+        try {
+            const obj: unknown = JSON.parse(line);
+            if (
+                obj !== null &&
+                typeof obj === 'object' &&
+                !Array.isArray(obj) &&
+                typeof (obj as Record<string, unknown>)['entity_id'] === 'string'
+            ) {
+                const rec = obj as Record<string, unknown>;
+                out.push({
+                    revoked_at: String(rec['revoked_at'] ?? ''),
+                    entity_id: rec['entity_id'] as string,
+                    reason: String(rec['reason'] ?? ''),
+                });
+            }
+        } catch {
+            // corrupt line — skip; never let one bad line crash the ledger read
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/user_memory_gate_counters.ts

@@ -0,0 +1,291 @@
+#!/usr/bin/env tsx
+/**
+ * The promotion-behaviour gate counters — road-to-global-user-memory Phase 5
+ * ("the gate that can actually fire").
+ *
+ * ADR-119 exists because a previous gate could never fire by construction:
+ * reuse could only accrue while the layer was ON, and ON was withheld pending
+ * reuse. ADR-138's Phase 5 gate is keyed to a different signal on purpose —
+ * **promotion behaviour**, which moves through human `/agents:user accept`
+ * decisions whether or not the global profile ever loads at session start.
+ * See `docs/decisions/ADR-138-global-user-profile-layer.md` § Promotion-
+ * behaviour gate for the kill-criterion this module's counters feed.
+ *
+ * Four counts, and nothing else:
+ *
+ *   1. `projects_with_ge_10_sessions`        — how many projects reached the
+ *      sessions floor the kill-criterion denominator needs.
+ *   2. `projects_with_promoted_observation`  — how many of those (or any)
+ *      projects have at least one promoted global observation.
+ *   3. `observations_proposed`               — total candidates that reached
+ *      the global buffer (Phase 2's `appendGlobalObservation` succeeding).
+ *   4. `observations_accepted`               — total candidates a human
+ *      confirmed via `/agents:user accept` (Phase 2's
+ *      `applyObservationToGlobalProfile` writing the profile).
+ *
+ * PII-exclusion-by-construction (the same shape `orchestration-telemetry.md`
+ * and `artifact-engagement-recording.md` already use): the counter struct has
+ * **no field capable of holding free-form content** — every field is a
+ * non-negative integer count. There is no `payload`, `notes`, or `context`
+ * field to widen by accident, and `readGateCounters` drops any unknown key or
+ * non-numeric value on read rather than passing it through. Privacy is a
+ * property of the shape, not of a scrubbing pass that could fail.
+ *
+ * This module never decides WHEN a project crosses the ≥10-session floor or
+ * WHEN a project's first observation gets promoted — those are caller-side
+ * facts (a session-start counter, the `/agents:user accept` flow) that the
+ * caller already holds in memory at the moment it happens. This module only
+ * durably persists the four resulting counts. Honest boundary: a
+ * read-then-write race between two concurrent callers can under-count by one
+ * increment — acceptable for a single-user local CLI with no lock primitive
+ * elsewhere in this package (`_lib/installed_lock.ts` tracks installed files,
+ * not a mutex), and irrelevant to the gate's 90-day-window granularity.
+ *
+ * Path resolution mirrors every sibling global-root artefact
+ * (`user_global_observations.ts`, `agent_user_profile.ts`): honours
+ * `$EVENT4U_CONFIG_HOME`, falls back to `~/.event4u/agent-config/`, and reads
+ * the legacy `~/.config/agent-config/` location for pre-migration installs.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as user_global_paths from './user_global_paths.js';
+
+/** Relative-to-root path of the gate counters file. */
+export const GATE_COUNTERS_RELATIVE = path.join('user', 'promotion-gate-counters.json');
+
+/**
+ * The gate's counter shape. Every field is a non-negative integer count —
+ * this interface can never carry a string, a path, an id, or an array; there
+ * is no field a caller could widen into free-form content without changing
+ * the type itself (verified by `tests/lib/user_memory_gate_counters.test.ts`'s
+ * shape test).
+ */
+/**
+ * The two project-level fields are **CANCELLED 2026-07-30** — kept in the struct
+ * so a reader finds the decision instead of the absence, never incremented. Both
+ * need a per-project record, and every primitive that can hold one either exposes
+ * the project set or, once coarsened past membership-testability, cannot resolve a
+ * 40% ratio at a cardinality in the tens. Reason + rejected candidates + the
+ * council review that forced the wording:
+ * agents/settings/contexts/promotion-gate-counting-primitive.md; the resulting
+ * narrowing of the kill criterion is recorded in ADR-138.
+ */
+export interface PromotionGateCounters {
+    readonly projects_with_ge_10_sessions: number;
+    readonly projects_with_promoted_observation: number;
+    readonly observations_proposed: number;
+    readonly observations_accepted: number;
+}
+
+/** The closed field set — anything else read from disk is dropped, never passed through. */
+export const GATE_COUNTER_FIELDS = [
+    'projects_with_ge_10_sessions',
+    'projects_with_promoted_observation',
+    'observations_proposed',
+    'observations_accepted',
+] as const satisfies readonly (keyof PromotionGateCounters)[];
+
+/** All-zero starting state. */
+export function zeroCounters(): PromotionGateCounters {
+    return {
+        projects_with_ge_10_sessions: 0,
+        projects_with_promoted_observation: 0,
+        observations_proposed: 0,
+        observations_accepted: 0,
+    };
+}
+
+/** `true` iff `value` is a non-negative integer — the only shape a counter field may hold. */
+function _isNonNegativeInteger(value: unknown): value is number {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+/**
+ * Coerce an arbitrary parsed-JSON value into a valid counters struct.
+ * Unknown keys are dropped; a field that is missing, non-numeric, negative,
+ * or non-integer falls back to `0` rather than throwing or passing the raw
+ * value through. This is the runtime half of the shape guarantee — the
+ * struct that comes out of a read can never carry anything the type doesn't
+ * already allow, even from a hand-edited or corrupted file on disk.
+ */
+export function coerceCounters(raw: unknown): PromotionGateCounters {
+    const rec =
+        raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+            ? (raw as Record<string, unknown>)
+            : {};
+    const zero = zeroCounters();
+    const out: Record<string, number> = { ...zero };
+    for (const field of GATE_COUNTER_FIELDS) {
+        const value = rec[field];
+        out[field] = _isNonNegativeInteger(value) ? value : 0;
+    }
+    return out as unknown as PromotionGateCounters;
+}
+
+// ---------------------------------------------------------------------------
+// Path resolution — mirrors user_global_observations.ts / agent_user_profile.ts.
+// ---------------------------------------------------------------------------
+
+/** Canonical write target for the gate counters file. */
+export function gateCountersWriteTarget(env?: user_global_paths.EnvMap | null): string {
+    return user_global_paths.write_target(GATE_COUNTERS_RELATIVE, { env: env ?? null });
+}
+
+/** Resolve the counters file's on-disk path — new namespace first, legacy fallback, `null` if neither exists. */
+export function resolveGateCountersPath(env?: user_global_paths.EnvMap | null): string | null {
+    return user_global_paths.resolve_with_fallback(GATE_COUNTERS_RELATIVE, { env: env ?? null });
+}
+
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+
+/** Read the current counters. Missing file, missing directory, or malformed JSON all resolve to `zeroCounters()` — never throws. */
+export function readGateCounters(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): PromotionGateCounters {
+    const target = resolveGateCountersPath(options.env ?? null);
+    if (target === null) {
+        return zeroCounters();
+    }
+    let raw: string;
+    try {
+        raw = fs.readFileSync(target, 'utf-8');
+    } catch {
+        return zeroCounters();
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return zeroCounters();
+    }
+    return coerceCounters(parsed);
+}
+
+/** Persist `counters` verbatim to the write target, creating the parent directory if needed. */
+function _writeGateCounters(
+    counters: PromotionGateCounters,
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): void {
+    const target = gateCountersWriteTarget(options.env ?? null);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(coerceCounters(counters)) + '\n', 'utf-8');
+}
+
+// ---------------------------------------------------------------------------
+// Pure increments — no disk access, easy to unit-test in isolation.
+// ---------------------------------------------------------------------------
+
+/** One project just crossed the ≥10-sessions floor. Caller dedupes per-project — this module holds no project identity. */
+export function incrementProjectsWithTenSessions(
+    counters: PromotionGateCounters,
+): PromotionGateCounters {
+    return { ...counters, projects_with_ge_10_sessions: counters.projects_with_ge_10_sessions + 1 };
+}
+
+/** One project just got its FIRST promoted global observation. Caller dedupes per-project — this module holds no project identity. */
+export function incrementProjectsWithPromotedObservation(
+    counters: PromotionGateCounters,
+): PromotionGateCounters {
+    return {
+        ...counters,
+        projects_with_promoted_observation: counters.projects_with_promoted_observation + 1,
+    };
+}
+
+/** One observation candidate reached the global buffer (a Phase 2/3 `appendGlobalObservation` success). */
+export function incrementObservationsProposed(
+    counters: PromotionGateCounters,
+): PromotionGateCounters {
+    return { ...counters, observations_proposed: counters.observations_proposed + 1 };
+}
+
+/** One observation candidate was confirmed via `/agents:user accept` (a Phase 2 `applyObservationToGlobalProfile` write). */
+export function incrementObservationsAccepted(
+    counters: PromotionGateCounters,
+): PromotionGateCounters {
+    return { ...counters, observations_accepted: counters.observations_accepted + 1 };
+}
+
+// ---------------------------------------------------------------------------
+// Disk-touching wrappers — read, increment, write, return the new value.
+// ---------------------------------------------------------------------------
+
+/** Record one project crossing the ≥10-sessions floor. */
+export function recordProjectReachedTenSessions(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): PromotionGateCounters {
+    const next = incrementProjectsWithTenSessions(readGateCounters(options));
+    _writeGateCounters(next, options);
+    return next;
+}
+
+/** Record one project's first promoted observation. */
+export function recordProjectPromotedFirstObservation(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): PromotionGateCounters {
+    const next = incrementProjectsWithPromotedObservation(readGateCounters(options));
+    _writeGateCounters(next, options);
+    return next;
+}
+
+/** Record one observation reaching the global buffer. */
+export function recordObservationProposed(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): PromotionGateCounters {
+    const next = incrementObservationsProposed(readGateCounters(options));
+    _writeGateCounters(next, options);
+    return next;
+}
+
+/** Record one observation confirmed via `/agents:user accept`. */
+export function recordObservationAccepted(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): PromotionGateCounters {
+    const next = incrementObservationsAccepted(readGateCounters(options));
+    _writeGateCounters(next, options);
+    return next;
+}
+
+// ---------------------------------------------------------------------------
+// Kill-criterion evaluation — see ADR-138 § Promotion-behaviour gate.
+// ---------------------------------------------------------------------------
+
+/** Human-confirmed floor: below this share of ≥10-session projects carrying a promotion, the teardown review is mandatory. */
+export const PROJECT_PROMOTION_SHARE_FLOOR = 0.4;
+
+/** Human-confirmed floor: below this review→accept rate, the teardown review is mandatory. */
+export const REVIEW_ACCEPT_RATE_FLOOR = 0.3;
+
+export interface KillCriterionResult {
+    /** `null` when `projects_with_ge_10_sessions` is `0` — the ratio is undefined, not zero, until there is a qualifying project. */
+    readonly project_promotion_share: number | null;
+    /** `null` when `observations_proposed` is `0` — same undefined-vs-zero distinction. */
+    readonly review_accept_rate: number | null;
+    /** `true` iff either floor is breached with a defined ratio — an undefined ratio never trips the gate on its own. */
+    readonly teardown_review_required: boolean;
+}
+
+/**
+ * Evaluate the two kill-criterion floors from ADR-138 § Promotion-behaviour
+ * gate against the current counters. A ratio with a zero denominator is
+ * reported as `null` (undefined), not `0` or `1` — an empty gate has not yet
+ * failed, it has not yet been exercised, and the ADR's window (90 days from
+ * release) is what turns "not yet exercised" into a real finding.
+ */
+export function evaluateKillCriterion(counters: PromotionGateCounters): KillCriterionResult {
+    const project_promotion_share =
+        counters.projects_with_ge_10_sessions > 0
+            ? counters.projects_with_promoted_observation / counters.projects_with_ge_10_sessions
+            : null;
+    const review_accept_rate =
+        counters.observations_proposed > 0
+            ? counters.observations_accepted / counters.observations_proposed
+            : null;
+    const teardown_review_required =
+        (project_promotion_share !== null && project_promotion_share < PROJECT_PROMOTION_SHARE_FLOOR) ||
+        (review_accept_rate !== null && review_accept_rate < REVIEW_ACCEPT_RATE_FLOOR);
+    return { project_promotion_share, review_accept_rate, teardown_review_required };
+}

package/src/scripts/_lib/worker_budget.ts

@@ -0,0 +1,107 @@
+/**
+ * Per-worker token stop-loss (L0b — road-to-lean-agent-init Phase 2).
+ *
+ * Pure, no-I/O. A dispatched worker carries a hard `max_tokens_per_worker`
+ * budget keyed by its resolved tier; on hit it returns a STRUCTURED PARTIAL
+ * RESULT + escalation flag to the orchestrator instead of continuing to
+ * explore. Live evidence (2026-07-28): four lookup-class workers burned
+ * 280–327k tokens each — a worker overrunning its budget 20× is a dispatch
+ * error on the wrong rung, not diligence.
+ *
+ * Composes with — replaces nothing:
+ * - the N=3 validation-loop budget (`autonomous-execution`),
+ * - the ADR-109 / `subagent-response-contract` body + 4-status envelope
+ *   (`subagent-steering`): the partial result rides as the body of a
+ *   `BLOCKED` envelope with `budget_hit: true` as the escalation flag.
+ */
+
+import type { Tier } from './subagent_routing.js';
+
+/**
+ * Start values — refined from Phase-3 telemetry (`budget_hit` rate in the
+ * audit stream), never final. `lite` is the roadmap-pinned lookup-class
+ * start value (~15k); `medium`/`high` are conservative seeds an order of
+ * magnitude below the observed 280–327k runaway runs.
+ */
+export const MAX_TOKENS_PER_WORKER: Readonly<Record<Exclude<Tier, 'inherit'>, number>> = {
+    lite: 15_000,
+    medium: 60_000,
+    high: 150_000,
+};
+
+/** Resolve the budget for a worker's tier; `inherit` uses the session tier's budget. */
+export function budgetForTier(tier: Tier, sessionTier: Exclude<Tier, 'inherit'> = 'high'): number {
+    const effective = tier === 'inherit' ? sessionTier : tier;
+    return MAX_TOKENS_PER_WORKER[effective];
+}
+
+/** Where the orchestrator should send the task after a budget hit. */
+export type NextRung = 'primitive' | 'higher-tier-subagent' | 'in-session';
+
+/**
+ * The structured partial result a budget-hit worker returns. Body of a
+ * `BLOCKED` envelope; `budget_hit: true` IS the escalation flag. Refs, not
+ * bodies — same privacy floor as the spawn/response contracts.
+ */
+export interface WorkerPartialResult {
+    budget_hit: true;
+    /** What was found so far — ref tokens (`file:line`, ids, paths), never bodies. */
+    found: string[];
+    /** What remains unexplored, one plain sentence. */
+    remaining: string;
+    /** Suggested next rung for the remainder. */
+    suggested_next_rung: NextRung;
+}
+
+const NEXT_RUNGS: ReadonlySet<string> = new Set<NextRung>(['primitive', 'higher-tier-subagent', 'in-session']);
+
+/** Ref-like guard — mirrors the spawn contract's refs-not-bodies invariant. */
+function isRefLike(s: unknown): s is string {
+    return typeof s === 'string' && s.length > 0 && s.length <= 200 && !s.includes('\n');
+}
+
+export interface BudgetEvaluation {
+    budget_hit: boolean;
+    consumed: number;
+    budget: number;
+    reason: string;
+}
+
+/** Evaluate consumption against the worker's budget. */
+export function evaluateWorkerBudget(consumed: number, budget: number): BudgetEvaluation {
+    const hit = consumed >= budget;
+    return {
+        budget_hit: hit,
+        consumed,
+        budget,
+        reason: hit
+            ? `budget hit (${consumed} >= ${budget}) — return partial result + escalation flag, stop exploring`
+            : `within budget (${consumed} < ${budget})`,
+    };
+}
+
+/**
+ * Validate a partial-result body. Returns the list of violations (empty =
+ * valid). The orchestrator never adopts an invalid partial return — it
+ * re-dispatches or resolves in-session per the synthesis duties.
+ */
+export function validateWorkerPartialResult(input: unknown): string[] {
+    const errors: string[] = [];
+    if (typeof input !== 'object' || input === null) return ['not an object'];
+    const r = input as Record<string, unknown>;
+
+    if (r['budget_hit'] !== true) errors.push('budget_hit must be literally true (the escalation flag)');
+    if (!Array.isArray(r['found'])) {
+        errors.push('found must be an array of ref tokens');
+    } else {
+        const bodyLike = (r['found'] as unknown[]).filter((x) => !isRefLike(x));
+        if (bodyLike.length > 0) errors.push(`found carries ${bodyLike.length} non-ref entr${bodyLike.length === 1 ? 'y' : 'ies'} (refs only, no bodies)`);
+    }
+    if (typeof r['remaining'] !== 'string' || (r['remaining'] as string).length === 0) {
+        errors.push('remaining must be a non-empty sentence');
+    }
+    if (typeof r['suggested_next_rung'] !== 'string' || !NEXT_RUNGS.has(r['suggested_next_rung'] as string)) {
+        errors.push(`suggested_next_rung must be one of ${[...NEXT_RUNGS].join(' | ')}`);
+    }
+    return errors;
+}