@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/lint_spawn_payload.ts

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * lint_spawn_payload — makes the `subagent-spawn-contract.md` Iron Law
+ * ("NEVER BULK-DUMP CONTEXT INTO A SUBAGENT") deterministic
+ * (road-to-lean-agent-init Phase 3).
+ *
+ * Scans two surfaces for spawn-brief-shaped payloads: (a) JSON fixtures
+ * matching `tests/fixtures/**\/*spawn*.json`; (b) fenced code blocks in
+ * `tests/reasoning-layer-eval/golden-transcripts/*.md` that either parse as
+ * JSON with both a `task` and a `knowledge_refs` key, or are introduced by
+ * nearby prose mentioning "spawn" + "task"/"brief".
+ *
+ * Three checks per payload found:
+ *   R1 inline-ref-body — a `knowledge_refs` entry with a newline or > 200
+ *      chars (mirrors `isRefLike` in `_lib/subagent_spawn.ts` — refs must be
+ *      pointers, never inline bodies).
+ *   R2 uncut-file-dump — the payload itself spans > 40 lines (a curated
+ *      brief is short; a 40+ line blob is a raw dump).
+ *   R3 over-cap — total payload size exceeds its tier's char cap: lite
+ *      8_000 / medium 16_000 / high 32_000 (SEED values, ~2k/4k/8k tokens at
+ *      ~4 chars/token). Unrecognised/absent tier caps at `high` — never guess
+ *      down. These are a first cut; the roadmap's Phase-3 `init_tokens`
+ *      telemetry is expected to refine them against a measured baseline, and
+ *      Phase 5's healthy-worker target (~1,500 tokens/worker) sits well
+ *      under even the `lite` cap.
+ *
+ * Warn-only by default. `--strict` flips findings to exit 2 — the promotion
+ * path once a clean observation window confirms the caps and detection
+ * heuristics don't false-positive on real traffic, per the same
+ * warn-then-promote pattern as `lint_skill_originality.ts`
+ * (`adr-architectural-consensus-mechanism`).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_spawn_payload            # warn-only (CI default)
+ *   ./scripts-run src/scripts/lint_spawn_payload --strict   # exit 2 on any finding
+ *   ./scripts-run src/scripts/lint_spawn_payload --quiet    # summary line only
+ *
+ * Exit codes: 0 = clean or warn-only findings, 2 = --strict + findings present.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+
+type Tier = 'lite' | 'medium' | 'high';
+
+/** Per-tier payload char cap — SEED values, see header comment. */
+const CAPS: Record<Tier, number> = { lite: 8_000, medium: 16_000, high: 32_000 };
+
+interface Finding {
+    rule: string;
+    file: string;
+    line: number;
+    snippet: string;
+}
+
+interface Payload {
+    file: string;
+    line: number;
+    text: string;
+    parsed: unknown;
+}
+
+function isTier(s: string): s is Tier {
+    return s === 'lite' || s === 'medium' || s === 'high';
+}
+
+/** Determine the payload's tier from a `tier` JSON field, then a nearby
+ * `tier: <x>` mention in the raw text; unknown → `high` (never guess down). */
+function detectTier(text: string, parsed: unknown): Tier {
+    if (parsed !== null && typeof parsed === 'object') {
+        const t = (parsed as Record<string, unknown>).tier;
+        if (typeof t === 'string' && isTier(t.toLowerCase())) return t.toLowerCase() as Tier;
+    }
+    const m = /\btier["']?\s*[:=]\s*["']?(lite|medium|high)\b/i.exec(text);
+    if (m?.[1] && isTier(m[1].toLowerCase())) return m[1].toLowerCase() as Tier;
+    return 'high';
+}
+
+function mk(p: Payload, rule: string, snippet: string): Finding {
+    return { rule, file: p.file, line: p.line, snippet };
+}
+
+/** The three checks, run against one identified spawn payload. */
+function checkPayload(p: Payload): Finding[] {
+    const out: Finding[] = [];
+
+    const lineCount = p.text.split('\n').length;
+    if (lineCount > 40) {
+        out.push(
+            mk(p, 'uncut-file-dump', `payload spans ${lineCount} lines (> 40) — looks like a raw file dump, not a curated brief`),
+        );
+    }
+
+    const tier = detectTier(p.text, p.parsed);
+    const cap = CAPS[tier];
+    if (p.text.length > cap) {
+        out.push(mk(p, 'over-cap', `payload is ${p.text.length} chars, over the '${tier}' cap of ${cap}`));
+    }
+
+    if (p.parsed !== null && typeof p.parsed === 'object') {
+        const refs = (p.parsed as Record<string, unknown>).knowledge_refs;
+        if (Array.isArray(refs)) {
+            for (const ref of refs) {
+                if (typeof ref !== 'string') continue;
+                if (ref.includes('\n')) {
+                    out.push(mk(p, 'inline-ref-body', 'knowledge_refs entry contains a newline — refs must be short pointers, never inline bodies'));
+                } else if (ref.length > 200) {
+                    out.push(mk(p, 'inline-ref-body', `knowledge_refs entry is ${ref.length} chars (> 200) — refs must be short pointers, never inline bodies`));
+                }
+            }
+        }
+    }
+
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Surface (a) — JSON fixtures matching tests/fixtures/**/*spawn*.json
+// ---------------------------------------------------------------------------
+function* walkFiles(dir: string): Generator<string> {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) yield* walkFiles(full);
+        else yield full;
+    }
+}
+
+function scanJsonFixture(filePath: string, repoRoot: string): Finding[] {
+    const rel = path.relative(repoRoot, filePath);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    let parsed: unknown = null;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        parsed = null;
+    }
+    return checkPayload({ file: rel, line: 1, text: raw, parsed });
+}
+
+// ---------------------------------------------------------------------------
+// Surface (b) — fenced spawn-payload blocks in golden transcripts
+// ---------------------------------------------------------------------------
+function scanMarkdownTranscript(filePath: string, repoRoot: string): Finding[] {
+    const rel = path.relative(repoRoot, filePath);
+    const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+    const findings: Finding[] = [];
+
+    let inBlock = false;
+    let fenceMarker = '';
+    let blockStart = -1;
+    let blockLines: string[] = [];
+    const contextWindow: string[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+
+        if (!inBlock) {
+            const openMatch = /^(```|~~~)/.exec(line);
+            if (openMatch?.[1]) {
+                inBlock = true;
+                fenceMarker = openMatch[1];
+                blockStart = i;
+                blockLines = [];
+                continue;
+            }
+            if (line.trim().length > 0) contextWindow.push(line.trim());
+            continue;
+        }
+
+        if (line.startsWith(fenceMarker)) {
+            const blockText = blockLines.join('\n');
+            let parsed: unknown = null;
+            try {
+                parsed = JSON.parse(blockText);
+            } catch {
+                parsed = null;
+            }
+            const parsedLooksLikeSpawn =
+                parsed !== null &&
+                typeof parsed === 'object' &&
+                Object.prototype.hasOwnProperty.call(parsed, 'task') &&
+                Object.prototype.hasOwnProperty.call(parsed, 'knowledge_refs');
+            const precedingContext = contextWindow.slice(-3).join(' ');
+            const contextLooksLikeSpawn = /spawn/i.test(precedingContext) && /(task|brief)/i.test(precedingContext);
+
+            if (parsedLooksLikeSpawn || contextLooksLikeSpawn) {
+                findings.push(...checkPayload({ file: rel, line: blockStart + 2, text: blockText, parsed }));
+            }
+
+            inBlock = false;
+            contextWindow.length = 0;
+            continue;
+        }
+
+        blockLines.push(line);
+    }
+
+    return findings;
+}
+
+function scanRepo(repoRoot: string): Finding[] {
+    const findings: Finding[] = [];
+
+    const fixturesDir = path.join(repoRoot, 'tests', 'fixtures');
+    for (const f of walkFiles(fixturesDir)) {
+        if (f.endsWith('.json') && /spawn/i.test(path.basename(f))) {
+            findings.push(...scanJsonFixture(f, repoRoot));
+        }
+    }
+
+    const transcriptsDir = path.join(repoRoot, 'tests', 'reasoning-layer-eval', 'golden-transcripts');
+    if (fs.existsSync(transcriptsDir)) {
+        for (const entry of fs.readdirSync(transcriptsDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                findings.push(...scanMarkdownTranscript(path.join(transcriptsDir, entry.name), repoRoot));
+            }
+        }
+    }
+
+    return findings;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function parseArgs(argv: readonly string[]): { strict: boolean; quiet: boolean } {
+    return { strict: argv.includes('--strict'), quiet: argv.includes('--quiet') };
+}
+
+function main(argv?: readonly string[], repoRootOverride?: string): number {
+    const args = parseArgs(argv ?? process.argv.slice(2));
+    const root = repoRootOverride ?? REPO_ROOT;
+    const findings = scanRepo(root);
+
+    if (!args.quiet) {
+        for (const f of findings) {
+            process.stdout.write(`⚠️  ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+        }
+    }
+
+    if (findings.length === 0) {
+        if (!args.quiet) process.stdout.write('✅  lint_spawn_payload: clean — no spawn-payload contract violations found.\n');
+        return 0;
+    }
+
+    if (args.strict) {
+        if (!args.quiet) {
+            process.stderr.write(`❌  lint_spawn_payload: ${findings.length} finding(s) under --strict.\n`);
+        }
+        return 2;
+    }
+
+    if (!args.quiet) {
+        process.stdout.write(
+            `\nlint_spawn_payload: ${findings.length} finding(s), warn-only. Promote with --strict once caps hold across a clean observation window.\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    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());
+}
+
+export { CAPS, checkPayload, detectTier, main, scanJsonFixture, scanMarkdownTranscript, scanRepo };
+export type { Finding, Payload, Tier };

package/src/scripts/lint_store_boundary.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Store-boundary lint — invariant 1 of ADR-130 (`subject` axis,
+ * road-to-reachable-code-memory Phase 8).
+ *
+ * Memory/knowledge INDEX code must not resolve the user-global store root
+ * itself: no `homedir(` call, no quoted `.event4u` literal, no
+ * `process.env.HOME` outside the sanctioned path modules. Global-root
+ * resolution is owned by exactly two modules (read-open/write-closed
+ * asymmetry lives behind them):
+ *
+ *   - src/scripts/_lib/user_global_paths.ts
+ *   - src/scripts/_lib/knowledge_global.ts
+ *
+ * Scan scope is the memory/knowledge index + retrieval + write-edge modules
+ * (SCAN_FILES below) — the surface that reads/writes memory records and must
+ * therefore stay partition-blind. Doc comments mentioning `~/.event4u/...`
+ * are prose, not resolution — only CODE literals match (quoted strings,
+ * call expressions, env access).
+ *
+ * Primary CI gate: tests/scripts/lint_store_boundary.test.ts (vitest,
+ * node-tests job) runs this against the real tree. Escape hatch for a
+ * deliberate example: a `// lint-store-boundary: ignore` comment on the
+ * same or preceding line.
+ *
+ * Exit codes: 0 clean · 1 violations · 2 usage · 3 internal.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Sanctioned owners of global-root resolution (repo-relative, POSIX). */
+export const SANCTIONED_MODULES: readonly string[] = [
+    'src/scripts/_lib/user_global_paths.ts',
+    'src/scripts/_lib/knowledge_global.ts',
+];
+
+/**
+ * Memory/knowledge index, retrieval, and write-edge modules — the
+ * partition-blind surface. Extend this list when a new index module lands.
+ */
+export const SCAN_FILES: readonly string[] = [
+    'src/scripts/memory_lookup.ts',
+    'src/scripts/memory_report.ts',
+    'src/scripts/memory_signal.ts',
+    'src/scripts/learning_sidecar.ts',
+    'src/scripts/memory_learn_hook.ts',
+    'src/scripts/second_brain_retrieval.ts',
+    'src/scripts/measure_lexical_ranking.ts',
+    'src/scripts/generate_knowledge_index.ts',
+    'src/scripts/_lib/lexical_index.ts',
+    'src/scripts/knowledge_global_cli.ts',
+];
+
+/** Code-literal patterns only — doc-comment prose does not match. */
+const GLOBAL_ROOT_RE = /homedir\s*\(|['"`][^'"`\n]*\.event4u|process\.env\.HOME\b|process\.env\[\s*['"]HOME['"]\s*\]/;
+const IGNORE_RE = /\/\/\s*lint-store-boundary:\s*ignore/;
+
+export interface Violation {
+    file: string;
+    line: number;
+    excerpt: string;
+}
+
+export function scanFile(absPath: string, relPath: string): Violation[] {
+    const out: Violation[] = [];
+    let text: string;
+    try {
+        text = fs.readFileSync(absPath, 'utf8');
+    } catch {
+        return out;
+    }
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!;
+        const trimmed = line.trimStart();
+        // Comment lines are prose (docblocks quote `~/.event4u/…` in markdown
+        // backticks) — only CODE can resolve a path.
+        if (trimmed.startsWith('*') || trimmed.startsWith('//') || trimmed.startsWith('/*')) continue;
+        if (!GLOBAL_ROOT_RE.test(line)) continue;
+        if (IGNORE_RE.test(line) || (i > 0 && IGNORE_RE.test(lines[i - 1]!))) continue;
+        out.push({ file: relPath, line: i + 1, excerpt: line.trim().slice(0, 120) });
+    }
+    return out;
+}
+
+export function run(root: string): Violation[] {
+    const violations: Violation[] = [];
+    for (const rel of SCAN_FILES) {
+        if (SANCTIONED_MODULES.includes(rel)) continue;
+        violations.push(...scanFile(path.join(root, rel), rel));
+    }
+    return violations;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let root = REPO_ROOT;
+    let format: 'text' | 'json' = 'text';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]!;
+        if (a === '--root') root = argv[++i] ?? root;
+        else if (a.startsWith('--root=')) root = a.slice('--root='.length);
+        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
+        else if (a.startsWith('--format=')) format = a.slice('--format='.length) as 'text' | 'json';
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_store_boundary [--root ROOT] [--format text|json]\n');
+            return 0;
+        } else {
+            process.stderr.write(`lint_store_boundary: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+    let violations: Violation[];
+    try {
+        violations = run(root);
+    } catch (exc) {
+        process.stderr.write(`lint_store_boundary: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+    if (format === 'json') {
+        process.stdout.write(`${JSON.stringify(violations, null, 2)}\n`);
+        return violations.length === 0 ? 0 : 1;
+    }
+    if (violations.length === 0) {
+        process.stdout.write('✅  store boundary clean — no global-root literal in index code.\n');
+        return 0;
+    }
+    process.stdout.write(`❌  ${violations.length} global-root literal(s) in index code:\n\n`);
+    for (const v of violations) {
+        process.stdout.write(`  🔴 ${v.file}:${v.line}  →  ${v.excerpt}\n`);
+    }
+    process.stdout.write(
+        '\nRoute global-store access through src/scripts/_lib/user_global_paths.ts ' +
+            'or src/scripts/_lib/knowledge_global.ts (ADR-130 invariant 1).\n',
+    );
+    return 1;
+}
+
+const _isMain = (() => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return pathToFileURL(fs.realpathSync(path.resolve(process.argv[1]))).href === import.meta.url;
+    } catch {
+        return pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+    }
+})();
+if (_isMain) {
+    process.exit(main());
+}

package/src/scripts/lint_versioned_cache.ts

@@ -17,6 +17,12 @@
  * the derived caches later phases create (B2 index, B3 learning sidecar, B5a
  * stat-index), not on directories or ordinary data files.
  *
+ * road-to-reachable-code-memory Phase 6: also covers `.sqlite3` / `.db` path
+ * literals — every derived SQLite store this suite writes (telemetry, the
+ * memory FTS index, the graph store) is exactly the "invalidate me on a
+ * format change" cache this lint exists to catch, and none of them carry a
+ * `-index`/`-cache` infix the original `.json`-only pattern required.
+ *
  * Usage: lint_versioned_cache.ts [--dir <root>] [--format text|json] [--quiet]
  * Exit codes: 0 = clean, 1 = usage error, 2 = violations found, 3 = internal.
  */
@@ -36,7 +42,7 @@ export const JUSTIFY_WINDOW = 6;
  * ordinary data/config JSON does not match.
  */
 export const CACHE_SUFFIX_RE =
-    /(?:^|[\/'"`\-.])(?:[a-z0-9_\-.]*)(?:-index|\.index|-cache|\.cache|\.stat-index|-stat-index|\.agent-learning)\.json(?:['"`]|$)/i;
+    /(?:^|[\/'"`\-.])(?:[a-z0-9_\-.]*)(?:(?:-index|\.index|-cache|\.cache|\.stat-index|-stat-index|\.agent-learning)\.json|\.sqlite3|\.db)(?:['"`]|$)/i;
 
 /** A version namespace present in the path literal itself. */
 const VERSION_IN_PATH_RE = /(?:[\/_\-.]v\d+|\$\{[^}]*[Vv]ersion[^}]*\}|\$\{[^}]*VERSION[^}]*\})/;

package/src/scripts/mcp_server/__main__.ts

@@ -14,10 +14,15 @@ import { fileURLToPath } from 'node:url';
 import { main } from './server.js';
 
 // Mirror `if __name__ == "__main__"`: run only when invoked directly,
-// not when imported. Compare the resolved module path to argv[1].
+// not when imported. Compare the resolved module path to argv[1]. Under
+// the esbuild bundle (dist/mcp/server.mjs) the build banner detects the
+// direct invocation before any module code runs, sets the global marker,
+// and rewrites argv[1] to a sentinel (so inlined modules' CLI-entry
+// guards cannot false-fire) — the marker is the bundle's signal here.
 const _selfPath = fileURLToPath(import.meta.url);
 const _invokedDirectly =
-    process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath);
+    (globalThis as { __AC_MCP_BUNDLE_DIRECT?: boolean }).__AC_MCP_BUNDLE_DIRECT === true ||
+    (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath));
 
 if (_invokedDirectly) {
     main();

package/src/scripts/mcp_server/catalog.ts

@@ -17,8 +17,21 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+// Bundled (dist/mcp/server.mjs) this module's dir is dist/mcp/, but the
+// catalog ships as source under src/scripts/mcp_server/ — the esbuild
+// --define sentinel picks the shipped location.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 const _CATALOG_FILE = path.join(
-    path.dirname(fileURLToPath(import.meta.url)),
+    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__
+        ? path.resolve(
+              path.dirname(fileURLToPath(import.meta.url)),
+              '..',
+              '..',
+              'src',
+              'scripts',
+              'mcp_server',
+          )
+        : path.dirname(fileURLToPath(import.meta.url)),
     'consumer_tool_catalog.json',
 );
 
@@ -44,6 +57,12 @@ export interface CatalogEntry {
     readonly side_effect: string;
     readonly implemented_on: readonly string[];
     readonly input_schema: Record<string, unknown>;
+    /**
+     * Honest MCP tool-behavior hints (Phase 3 of road-to-credible-install),
+     * e.g. `{ readOnlyHint: true }`. Present only for implemented tools —
+     * optional so the field stays backward-compatible with schema_version 1.
+     */
+    readonly annotations?: Record<string, unknown>;
 }
 
 /** Refuse to boot on a malformed catalog. Boot-time errors only. */
@@ -112,6 +131,9 @@ export function load_catalog(targetPath?: string): CatalogEntry[] {
             (v) => v as string,
         ),
         input_schema: t.input_schema as Record<string, unknown>,
+        ...(t.annotations !== undefined && t.annotations !== null
+            ? { annotations: t.annotations as Record<string, unknown> }
+            : {}),
     }));
 }