@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -26,6 +26,11 @@
  *   - already `rtk …` wrapped, or piped / compound (`|`, `&&`, `||`, `;`)
  *   - any program not in the verbose-CLI allowlist
  *
+ * Second branch (token-economy-cache Phase 4.2, advisory-degraded): for
+ * commands rtk cannot wrap — an unbounded tree-wide search per the committed
+ * OUTPUT_CAP_TABLE below — emit a warn naming the bounded alternative. No
+ * rewrite, no truncation; see the table's comment for the degradation record.
+ *
  * Exit codes (dispatcher contract): 0 allow · 2 warn (+ JSON reason on stdout).
  */
 import fs from "node:fs";
@@ -175,6 +180,108 @@ export function classify(command: string): Eligibility {
   return { eligible: true, program };
 }
 
+// ── Unbounded-output cap ADVISORY (token-economy-cache Phase 4.2) ──────────
+// The roadmap step asked for a deterministic PreToolUse cap REWRITE; the v1
+// dispatcher contract carries no `updatedInput`, so per the roadmap's
+// pre-registered consequence this degrades to an ADVISORY: a committed
+// per-command cap table (this constant — rows individually removable,
+// per-row opt-out via `enabled`) and a warn naming the bounded alternative.
+// Nothing is ever truncated; ignoring the advisory IS the uncapped re-run,
+// and repeated fires in the dispatcher's warn counters are the demand
+// signal that calibrates the table. Table scope is evidence-bound: only the
+// class the 2026-08-10 corpus run measured (tree-wide search — 302 KB raw
+// vs 21 KB bounded on this repo; internal/bench/rtk-savings/RESULTS.md).
+export interface CapRow {
+  enabled: boolean;
+  /** long flags whose presence means the output is already bounded */
+  bounded_long_flags: readonly string[];
+  /** short-option letters (combined forms like `-rln` count) that bound output */
+  bounded_short_letters: string;
+  /** fire only when a recursive/tree-wide flag is present ("" = always tree-wide) */
+  recursive_short_letters: string;
+  recursive_long_flags: readonly string[];
+  hint: string;
+}
+
+export const OUTPUT_CAP_TABLE: Readonly<Record<string, CapRow>> = {
+  grep: {
+    enabled: true,
+    bounded_long_flags: ["--files-with-matches", "--count", "--max-count"],
+    bounded_short_letters: "lcm",
+    recursive_short_letters: "rR",
+    recursive_long_flags: ["--recursive", "--dereference-recursive"],
+    hint: "add `-l` (files only) or `-m 5` (per-file cap), or pipe through `| head -n 100`",
+  },
+  rg: {
+    enabled: true,
+    bounded_long_flags: ["--files-with-matches", "--count", "--max-count", "--count-matches"],
+    bounded_short_letters: "lcm",
+    recursive_short_letters: "",
+    recursive_long_flags: [],
+    hint: "add `-l` (files only) or `--max-count 5`, or pipe through `| head -n 100`",
+  },
+};
+
+/** Pipeline members that already bound or consume the stream. */
+const _BOUNDING_PROGRAMS: ReadonlySet<string> = new Set(["head", "tail", "wc", "rtk"]);
+
+function _shortLetters(token: string): string | null {
+  return /^-[A-Za-z]+$/.test(token) ? token.slice(1) : null;
+}
+
+function _hasAnyFlag(group: readonly string[], longFlags: readonly string[], shortLetters: string): boolean {
+  for (const t of group) {
+    if (longFlags.some((f) => t === f || t.startsWith(`${f}=`))) return true;
+    const letters = _shortLetters(t);
+    if (letters && shortLetters && [...shortLetters].some((c) => letters.includes(c))) return true;
+  }
+  return false;
+}
+
+export interface CapVerdict {
+  program: string;
+  hint: string;
+}
+
+/**
+ * An unbounded tree-wide search in the command (any pipeline segment) with no
+ * bounding flag and no bounding pipeline member → advisory verdict. Fail-open:
+ * parse errors and anything ambiguous return null.
+ */
+export function classifyCap(
+  command: string,
+  table: Readonly<Record<string, CapRow>> = OUTPUT_CAP_TABLE,
+): CapVerdict | null {
+  const cmd = command.trim();
+  if (!cmd) return null;
+  let tokens: string[];
+  try {
+    tokens = shlexSplit(cmd);
+  } catch (e) {
+    if (e instanceof ShlexError) return null;
+    throw e;
+  }
+  const groups = _split_subcommands(tokens);
+  let hit: CapVerdict | null = null;
+  for (const group of groups) {
+    let i = 0;
+    while (i < group.length && _is_env_assignment(group[i] as string)) i += 1;
+    const program = group[i];
+    if (!program) continue;
+    // A bounding consumer anywhere in the chain (head/tail/wc/rtk) → bounded.
+    if (_BOUNDING_PROGRAMS.has(program)) return null;
+    const row = table[program];
+    if (!row || !row.enabled) continue;
+    const needsRecursive = row.recursive_short_letters !== "" || row.recursive_long_flags.length > 0;
+    if (needsRecursive && !_hasAnyFlag(group, row.recursive_long_flags, row.recursive_short_letters)) {
+      continue; // single-file / non-tree invocation — not the measured class
+    }
+    if (_hasAnyFlag(group, row.bounded_long_flags, row.bounded_short_letters)) continue;
+    if (hit === null) hit = { program, hint: row.hint };
+  }
+  return hit;
+}
+
 function _readStdin(): string {
   return readHookStdin();
 }
@@ -203,6 +310,9 @@ export function main(): number {
         : ".";
   if (!_enabled(root)) return EXIT_ALLOW;
 
+  const command = _extract_command(envelope);
+  if (!command) return EXIT_ALLOW;
+
   // Deterministic gate: the live probe, NOT a self-reported flag — and an
   // IDENTITY probe, not bare presence: the `rtk` binary name collides with
   // the unrelated Rust Type Kit, and nudging the agent to wrap commands with
@@ -211,21 +321,30 @@ export function main(): number {
   // NOT — fail closed for behavior, fail open for the command itself.
   // Identity is cached user-globally keyed on the binary's path+mtime+size,
   // so the `rtk gain` probe runs once per installed binary, not per command.
-  if (!rtk_available()) return EXIT_ALLOW;
-  if (detectRtkCached().identity !== "token-killer") return EXIT_ALLOW;
-
-  const command = _extract_command(envelope);
-  if (!command) return EXIT_ALLOW;
-
-  const verdict = classify(command);
-  if (!verdict.eligible) return EXIT_ALLOW;
+  if (rtk_available() && detectRtkCached().identity === "token-killer") {
+    const verdict = classify(command);
+    if (verdict.eligible) {
+      const reason =
+        `rtk is installed and wraps verbose CLI output (upstream reports 60–90% fewer output tokens). ` +
+        `Re-run wrapped: \`rtk ${command.trim()}\`. ` +
+        `(Skip for completeness-critical output like \`git diff\`.)`;
+      process.stdout.write(`${_jsonReason(reason)}\n`);
+      return EXIT_WARN;
+    }
+  }
 
-  const reason =
-    `rtk is installed and wraps verbose CLI output (upstream reports 60–90% fewer output tokens). ` +
-    `Re-run wrapped: \`rtk ${command.trim()}\`. ` +
-    `(Skip for completeness-critical output like \`git diff\`.)`;
-  process.stdout.write(`${_jsonReason(reason)}\n`);
-  return EXIT_WARN;
+  // Cap advisory needs no rtk — it covers exactly the commands rtk cannot
+  // wrap (compound/piped, or outside its allowlist).
+  const cap = classifyCap(command);
+  if (cap) {
+    const reason =
+      `Unbounded \`${cap.program}\` output: a tree-wide search can return hundreds of KB into context ` +
+      `(measured here: 302 KB raw vs 21 KB bounded — internal/bench/rtk-savings/RESULTS.md). ` +
+      `Prefer a bounded form — ${cap.hint}. Re-running unbounded is fine when completeness is required.`;
+    process.stdout.write(`${_jsonReason(reason)}\n`);
+    return EXIT_WARN;
+  }
+  return EXIT_ALLOW;
 }
 
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where

package/src/scripts/hooks/session_eol_hook.ts

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * session-eol — Stop-slot session end-of-life instrument + recycle advisory
+ * (road-to-token-economy-recycling Phases 1.1 / 3.2 / 4.2).
+ *
+ * Phase 1.1 (record-only): per session, maintain counts-only end-of-life
+ * state — final main-chain context size in parsed tokens (via
+ * `_lib/session_eol.ts` → `cc_transcript.billableInputTokens`), turn count,
+ * and every observed compaction event — under
+ * `agents/runtime/state/session-eol/<sha256(session)>.json`. Incremental:
+ * each Stop reads only the transcript bytes appended since the last scan.
+ *
+ * Phase 3.2 (advisory, once per session): past the committed recycle
+ * threshold (`src/config/recycle-threshold-budget.json`), inject ONE line
+ * advising `session:recycle` — the F2 once-per-session pattern of
+ * `end_review_nudge_hook.ts`. Absent/unreadable config or transcript is
+ * SILENCE, never a block (fail-open); hooks cannot inject `/clear`, so the
+ * recycle action itself stays advisory-carried by design (roadmap 5.1).
+ *
+ * Phase 4.2 (read surface): every Stop also overwrites
+ * `agents/runtime/state/context-fill.json` with the machine-readable fill
+ * level + threshold state — display substrate for an external statusline;
+ * carries counts only, and this hook's behaviour is identical whether or
+ * not anything reads it.
+ *
+ * Never blocks: exit 0 on every silent path; the advisory reports at
+ * exit 2 ({decision:"warn", additional_context}) which `host_semantics`
+ * reduces to a non-blocking warn on claude. `AGENT_CONFIG_REPLAY=1` → no-op.
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
+
+import {
+    emptyCounters,
+    readNewCompleteLines,
+    scanEolSlice,
+    type EolCounters,
+} from '../_lib/session_eol.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json, is_replay_mode } from './state_io.js';
+import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
+
+const EXIT_WARN = 2;
+
+/**
+ * Per-process threshold override — the test seam and the emergency off
+ * switch (`0` or any non-positive value disables the advisory lane while
+ * recording continues). The committed value lives in
+ * `src/config/recycle-threshold-budget.json` and is statically imported so
+ * the hook bundle carries it into consumers — one threshold, one constant.
+ */
+export const THRESHOLD_OVERRIDE_ENV = 'AGENT_RECYCLE_THRESHOLD_TOKENS';
+
+/** Machine-readable fill-level surface (Phase 4.2). Counts only, overwritten per Stop. */
+export const CONTEXT_FILL_REL = path.join('agents', 'runtime', 'state', 'context-fill.json');
+
+export interface SessionEolState {
+    schema_version: 1;
+    counters: EolCounters;
+    /** ISO stamp when the recycle advisory fired for this session (F2), or null. */
+    advisory_fired_at: string | null;
+    updated_at: string;
+}
+
+function str(value: JsonValue | undefined): string {
+    return typeof value === 'string' ? value : '';
+}
+
+function stateDir(workspaceRoot: string): string {
+    return path.join(workspaceRoot, 'agents', 'runtime', 'state', 'session-eol');
+}
+
+export function stateFile(workspaceRoot: string, sessionKey: string): string {
+    return path.join(stateDir(workspaceRoot), `${sessionKey}.json`);
+}
+
+/** Same derivation as `end_review_nudge_hook.deriveSessionKey` — hashed, never raw. */
+export function deriveSessionKey(envelope: JsonObject, payload: JsonObject): string {
+    const raw =
+        str(envelope['session_id'] as JsonValue | undefined) ||
+        str((payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined);
+    return crypto.createHash('sha256').update(raw || 'unknown-session').digest('hex');
+}
+
+/** Load prior per-session state; any read/shape error reads as "fresh session". */
+export function readState(file: string): SessionEolState {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as Partial<SessionEolState>;
+        if (
+            parsed &&
+            typeof parsed === 'object' &&
+            parsed.schema_version === 1 &&
+            parsed.counters &&
+            typeof parsed.counters.scanned_bytes === 'number'
+        ) {
+            return {
+                schema_version: 1,
+                counters: parsed.counters,
+                advisory_fired_at:
+                    typeof parsed.advisory_fired_at === 'string' ? parsed.advisory_fired_at : null,
+                updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : '',
+            };
+        }
+    } catch {
+        // fall through — fresh state
+    }
+    return {
+        schema_version: 1,
+        counters: emptyCounters(),
+        advisory_fired_at: null,
+        updated_at: '',
+    };
+}
+
+/**
+ * Resolve the recycle threshold (Phase 3.1): the per-process override wins
+ * (tests; `0` = advisory lane off), else the committed constant from
+ * `recycle-threshold-budget.json`. Returns `null` when the lane is
+ * disabled or the value is not a positive number — recording continues
+ * either way (fail-open, never a block).
+ */
+export function readThresholdTokens(): number | null {
+    const override = process.env[THRESHOLD_OVERRIDE_ENV];
+    if (override !== undefined) {
+        const value = Number(override);
+        return Number.isFinite(value) && value > 0 ? value : null;
+    }
+    const value = (recycleThresholdConfig as Record<string, unknown>)['recycle_threshold_tokens'];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/** The exactly-one advisory line injected past threshold (Phase 3.2). */
+export function buildAdvisoryLine(tokens: number, threshold: number): string {
+    return (
+        `context past recycle threshold (${tokens.toLocaleString('en-US')} of ` +
+        `${threshold.toLocaleString('en-US')} tokens): run \`agent-config session:recycle\` to ` +
+        `write the recycle envelope, then /clear — the successor session resumes from the ` +
+        `envelope at session_start (road-to-token-economy-recycling)`
+    );
+}
+
+/** Overwrite the Phase 4.2 read surface. Counts only; failures are swallowed. */
+function writeContextFill(
+    workspaceRoot: string,
+    tokens: number | null,
+    threshold: number | null,
+    ts: string,
+): void {
+    try {
+        atomic_write_json(path.join(workspaceRoot, CONTEXT_FILL_REL), {
+            schema_version: 1,
+            final_context_tokens: tokens,
+            recycle_threshold_tokens: threshold,
+            past_threshold: tokens !== null && threshold !== null && tokens >= threshold,
+            updated_at: ts,
+        });
+    } catch {
+        // a state-write failure must never block the Stop path
+    }
+}
+
+export function main(): number {
+    const [envelope, payload] = unwrap(readHookStdin(), 'claude');
+
+    const event = String(envelope['event'] ?? '');
+    if (event !== '' && event !== 'stop') {
+        return 0;
+    }
+    if (is_replay_mode()) {
+        return 0; // replay fixtures never mutate session state
+    }
+
+    const workspaceRoot = String(envelope['workspace_root'] ?? '').trim() || process.cwd();
+
+    const transcriptPath = str(
+        (payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined,
+    ).trim();
+    if (!transcriptPath || !isSafeTranscriptPath(transcriptPath)) {
+        return 0; // no readable ledger — silence, never a block
+    }
+
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const file = stateFile(workspaceRoot, sessionKey);
+    const state = readState(file);
+
+    let counters = state.counters;
+    const read = readNewCompleteLines(transcriptPath, counters.scanned_bytes);
+    if (read.truncated) {
+        const full = readNewCompleteLines(transcriptPath, 0);
+        counters = scanEolSlice(full.text, emptyCounters());
+        counters.scanned_bytes = full.nextOffset;
+    } else if (read.text.length > 0) {
+        counters = scanEolSlice(read.text, counters);
+        counters.scanned_bytes = read.nextOffset;
+    } else {
+        counters = { ...counters, scanned_bytes: read.nextOffset };
+    }
+
+    const now = new Date().toISOString();
+    const threshold = readThresholdTokens();
+    const tokens = counters.final_context_tokens;
+
+    const shouldAdvise =
+        threshold !== null &&
+        tokens !== null &&
+        tokens >= threshold &&
+        state.advisory_fired_at === null;
+
+    const nextState: SessionEolState = {
+        schema_version: 1,
+        counters,
+        advisory_fired_at: shouldAdvise ? now : state.advisory_fired_at,
+        updated_at: now,
+    };
+    try {
+        atomic_write_json(file, nextState);
+    } catch {
+        // recording is best-effort; never block the Stop path
+    }
+
+    writeContextFill(workspaceRoot, tokens, threshold, now);
+
+    if (shouldAdvise && threshold !== null && tokens !== null) {
+        process.stdout.write(
+            `${JSON.stringify({
+                decision: 'warn',
+                reason: `session-eol: context ${tokens} >= recycle threshold ${threshold}`,
+                additional_context: buildAdvisoryLine(tokens, threshold),
+            })}\n`,
+        );
+        return EXIT_WARN;
+    }
+    return 0;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}