@event4u/agent-config 8.2.0 → 8.4.0

package/src/scripts/lint_surface_matrix.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Lint src/config/surface-matrix.yml — the machine-checked per-tool
+ * canonical-surface inventory (road-to-install-path-convergence Phase 2).
+ *
+ * Guarantees:
+ *   - every tool in install.ts::USER_SCOPE_PATHS has a matrix entry, and the
+ *     matrix declares no tool the installer does not know (set equality)
+ *   - each entry's scope_path matches USER_SCOPE_PATHS (drift fails)
+ *   - surface / hooks values come from the closed enums
+ *   - duplicate.detect.all_of paths are user-scope (~/) or repo-relative
+ *     (./); repo-relative paths must resolve on disk
+ *   - a defined duplicate class must carry a converge action, and the
+ *     claude-code converge command must name the real plugin id (drift guard
+ *     against _lib/claude_plugin.ts)
+ *
+ * Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import YAML from 'yaml';
+
+import { USER_SCOPE_PATHS } from './install.js';
+import { CLAUDE_MARKETPLACE_NAME, CLAUDE_PLUGIN_ID } from './_lib/claude_plugin.js';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+export const MATRIX_PATH = path.join(REPO_ROOT, 'src', 'config', 'surface-matrix.yml');
+
+const SURFACE_VALUES = new Set(['projection', 'plugin', 'bundles', 'export-only']);
+const HOOKS_VALUES = new Set(['managed-settings-block', 'settings-hooks-opt-in', 'plugin', 'none']);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+export interface SurfaceMatrixTool {
+    surface: string;
+    scope_path: string;
+    hooks: string;
+    duplicate?: {
+        description?: string;
+        pending_evidence?: string;
+        detect?: { all_of?: string[] };
+    };
+    converge?: { action?: string; command?: string; reaps?: string[] };
+    notes?: string;
+}
+
+export function load_surface_matrix(matrixPath: string = MATRIX_PATH): Record<string, SurfaceMatrixTool> {
+    const raw = YAML.parse(fs.readFileSync(matrixPath, 'utf-8'), { version: '1.1' }) as JsonObject;
+    const tools = raw['tools'];
+    if (!isObject(tools)) {
+        throw new Error('surface-matrix.yml: `tools` must be a mapping');
+    }
+    return tools as unknown as Record<string, SurfaceMatrixTool>;
+}
+
+export function main(): number {
+    if (!fs.existsSync(MATRIX_PATH)) {
+        process.stdout.write(`❌  ${MATRIX_PATH} not found\n`);
+        return 1;
+    }
+
+    const errors: string[] = [];
+    let tools: Record<string, SurfaceMatrixTool>;
+    try {
+        tools = load_surface_matrix();
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stdout.write(`❌  surface-matrix.yml unreadable: ${msg}\n`);
+        return 1;
+    }
+
+    // Coverage — set equality with the installer's tool inventory.
+    const matrixIds = new Set(Object.keys(tools));
+    const installerIds = new Set(Object.keys(USER_SCOPE_PATHS));
+    for (const id of installerIds) {
+        if (!matrixIds.has(id)) {
+            errors.push(`tool \`${id}\` is in USER_SCOPE_PATHS but has no surface-matrix entry`);
+        }
+    }
+    for (const id of matrixIds) {
+        if (!installerIds.has(id)) {
+            errors.push(`tool \`${id}\` is in the surface matrix but not in USER_SCOPE_PATHS`);
+        }
+    }
+
+    for (const [id, entry] of Object.entries(tools)) {
+        const where = `tools.${id}`;
+        if (!isObject(entry)) {
+            errors.push(`${where} must be a mapping`);
+            continue;
+        }
+        if (!SURFACE_VALUES.has(entry.surface)) {
+            errors.push(`${where}.surface \`${String(entry.surface)}\` not in {${[...SURFACE_VALUES].join(', ')}}`);
+        }
+        if (!HOOKS_VALUES.has(entry.hooks)) {
+            errors.push(`${where}.hooks \`${String(entry.hooks)}\` not in {${[...HOOKS_VALUES].join(', ')}}`);
+        }
+        const expectedPath = USER_SCOPE_PATHS[id];
+        if (expectedPath && entry.scope_path !== expectedPath) {
+            errors.push(
+                `${where}.scope_path \`${String(entry.scope_path)}\` drifted from ` +
+                    `USER_SCOPE_PATHS \`${expectedPath}\``,
+            );
+        }
+
+        const dup = entry.duplicate;
+        if (dup !== undefined) {
+            if (!isObject(dup)) {
+                errors.push(`${where}.duplicate must be a mapping`);
+                continue;
+            }
+            const detect = dup.detect;
+            if (detect !== undefined) {
+                const allOf = isObject(detect) ? detect['all_of'] : undefined;
+                if (!Array.isArray(allOf) || allOf.length === 0) {
+                    errors.push(`${where}.duplicate.detect.all_of must be a non-empty list`);
+                } else {
+                    for (const p of allOf) {
+                        if (typeof p !== 'string' || !(p.startsWith('~/') || p.startsWith('./'))) {
+                            errors.push(
+                                `${where}.duplicate.detect path \`${String(p)}\` must start with ~/ or ./`,
+                            );
+                            continue;
+                        }
+                        if (p.startsWith('./') && !fs.existsSync(path.join(REPO_ROOT, p.slice(2)))) {
+                            errors.push(`${where}.duplicate.detect repo path does not resolve: \`${p}\``);
+                        }
+                    }
+                }
+                // A defined (non-pending) duplicate class needs a converge action.
+                const conv = entry.converge;
+                if (!isObject(conv) || typeof conv['command'] !== 'string' || conv['command'] === '') {
+                    errors.push(`${where} defines a duplicate class but no converge.command`);
+                }
+            } else if (typeof dup['pending_evidence'] !== 'string') {
+                errors.push(
+                    `${where}.duplicate must carry either detect.all_of or pending_evidence`,
+                );
+            }
+        }
+    }
+
+    // Drift guard: the claude-code converge command must name the real
+    // plugin id + marketplace name from _lib/claude_plugin.ts.
+    const claude = tools['claude-code'];
+    const claudeCmd = claude && isObject(claude.converge) ? String(claude.converge['command'] ?? '') : '';
+    const expectedRef = `${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`;
+    if (claudeCmd !== '' && !claudeCmd.includes(expectedRef)) {
+        errors.push(
+            `tools.claude-code.converge.command must reference \`${expectedRef}\` ` +
+                `(got \`${claudeCmd}\`)`,
+        );
+    }
+
+    if (errors.length > 0) {
+        process.stdout.write('❌  surface-matrix.yml has problems:\n');
+        for (const e of errors) {
+            process.stdout.write(`  - ${e}\n`);
+        }
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  surface-matrix.yml (${matrixIds.size} tools, coverage matches USER_SCOPE_PATHS)\n`,
+    );
+    process.stdout.write('  No issues found.\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()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`❌  internal error: ${msg}\n`);
+        process.exit(3);
+    }
+}

package/src/scripts/mcp_exec/safety_envelope.ts

@@ -0,0 +1,105 @@
+// Compiled safety envelope for MCP shell-exec tools.
+//
+// Lives OUTSIDE src/scripts/mcp_server/ on purpose: the A0 contract bans
+// direct child_process imports in mcp_server modules; approved exec-tier
+// tools lazy-import this module instead (same transitive pattern as the
+// roadmap_archive handler's git effects — accepted by the 2026-07-07
+// council verdict, agents/decisions/mcp-write-exec-cut-2026-07-07.md).
+//
+// The envelope is compiled policy, not configuration (council Decision 2):
+//   - argv array, never a shell string — caller-supplied values cannot be
+//     interpolated into a command line;
+//   - hard timeout — the child is killed, never awaited indefinitely;
+//   - output cap per stream — a runaway process cannot flood the MCP
+//     response;
+//   - long-running policy is synchronous truncation (roadmap Phase 5
+//     Step 4): no job queue, no polling — a call that exceeds the timeout
+//     returns timed_out: true with whatever output was captured.
+//
+// Network isolation is NOT promised here: a spawned test runner executes
+// arbitrary project test code, which may itself use the network. The
+// envelope constrains the spawn surface (no shell, bounded time, bounded
+// output), not the semantics of the tool under test — stated explicitly
+// in the A0 amendment.
+
+import { execFile } from 'node:child_process';
+
+export interface EnvelopeSpec {
+    /** argv[0] is the executable; the rest are literal arguments. No shell. */
+    readonly argv: readonly string[];
+    /** Working directory for the child (the consumer root). */
+    readonly cwd: string;
+    /** Hard kill deadline in milliseconds. */
+    readonly timeout_ms: number;
+    /** Per-stream output cap in bytes; excess is truncated, flagged. */
+    readonly max_output_bytes: number;
+}
+
+export interface EnvelopeResult {
+    exit_code: number | null;
+    timed_out: boolean;
+    stdout: string;
+    stdout_truncated: boolean;
+    stderr: string;
+    stderr_truncated: boolean;
+    duration_ms: number;
+    argv: string[];
+}
+
+function _truncate(text: string, cap: number): [string, boolean] {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.byteLength <= cap) {
+        return [text, false];
+    }
+    return [buf.subarray(0, cap).toString('utf8'), true];
+}
+
+/**
+ * Run `spec.argv` under the compiled envelope and resolve with a
+ * structured result. Never rejects for child failure — a non-zero exit,
+ * timeout, or spawn error all surface inside the result object so the
+ * MCP handler can return them as data.
+ */
+export function run_enveloped(spec: EnvelopeSpec): Promise<EnvelopeResult> {
+    const started = Date.now();
+    const [cmd, ...args] = spec.argv;
+    if (cmd === undefined) {
+        throw new Error('envelope argv must not be empty');
+    }
+    return new Promise((resolve) => {
+        execFile(
+            cmd,
+            args,
+            {
+                cwd: spec.cwd,
+                timeout: spec.timeout_ms,
+                killSignal: 'SIGKILL',
+                windowsHide: true,
+                // Cap the in-memory buffer a little above the reported cap so
+                // truncation is ours (flagged), not execFile's (thrown).
+                maxBuffer: spec.max_output_bytes + 64 * 1024,
+                encoding: 'utf8',
+            },
+            (error, stdout, stderr) => {
+                const timedOut = Boolean(error && 'killed' in error && error.killed === true);
+                let exitCode: number | null = 0;
+                if (error) {
+                    const code = (error as NodeJS.ErrnoException & { code?: unknown }).code;
+                    exitCode = typeof code === 'number' ? code : null;
+                }
+                const [out, outTrunc] = _truncate(String(stdout ?? ''), spec.max_output_bytes);
+                const [err, errTrunc] = _truncate(String(stderr ?? ''), spec.max_output_bytes);
+                resolve({
+                    exit_code: timedOut ? null : exitCode,
+                    timed_out: timedOut,
+                    stdout: out,
+                    stdout_truncated: outTrunc,
+                    stderr: err,
+                    stderr_truncated: errTrunc,
+                    duration_ms: Date.now() - started,
+                    argv: [...spec.argv],
+                });
+            },
+        );
+    });
+}

package/src/scripts/mcp_registry_submit.sh

@@ -132,9 +132,16 @@ cd "$WORKDIR"
 gh repo clone "$FORK_REPO" registry-fork
 cd registry-fork
 
-# Add upstream + sync default branch.
+# Add upstream + sync default branch. `gh repo clone` of a fork already
+# wires an `upstream` remote pointing at the parent — make the add
+# idempotent (set-url) instead of dying on "remote upstream already
+# exists" (the exact failure observed on the 2026-07-07 live run).
 DEFAULT_BRANCH=$(gh repo view "$REGISTRY" --json defaultBranchRef --jq .defaultBranchRef.name)
-git remote add upstream "https://github.com/$REGISTRY.git"
+if git remote get-url upstream >/dev/null 2>&1; then
+  git remote set-url upstream "https://github.com/$REGISTRY.git"
+else
+  git remote add upstream "https://github.com/$REGISTRY.git"
+fi
 git fetch upstream "$DEFAULT_BRANCH"
 git checkout -b "$BRANCH" "upstream/$DEFAULT_BRANCH"
 
@@ -155,10 +162,14 @@ _step "Pushing branch $BRANCH to fork"
 git push -u origin "$BRANCH"
 
 _step "Opening PR against $REGISTRY"
+# gh pr create expects --head as OWNER:branch (not OWNER/REPO:branch) —
+# the repo form fails with "Head sha can't be blank" (observed on the
+# 2026-07-07 live run).
+FORK_OWNER="${FORK_REPO%%/*}"
 PR_URL=$(gh pr create \
   --repo "$REGISTRY" \
   --base "$DEFAULT_BRANCH" \
-  --head "$FORK_REPO:$BRANCH" \
+  --head "$FORK_OWNER:$BRANCH" \
   --title "Add event4u/agent-config — universal AI agent OS" \
   --body "$(cat <<'EOF'
 Adds [`event4u/agent-config`](https://github.com/event4u-app/agent-config) to the registry.

package/src/scripts/mcp_server/__main__.ts

@@ -1,11 +1,9 @@
-// Entrypoint — TS twin of `scripts/mcp_server/__main__.py`
-// (`python -m scripts.mcp_server`).
-//
-// Required by Claude Desktop / Zed / Continue stdio-server config on the
-// Python side; the .py stays the runtime entry until a later phase (glama
-// still launches `python -m scripts.mcp_server`). This twin coexists and
-// forwards to `server.main()`; keep this file flat so crash stack traces
-// point at server.ts, not the bootstrap.
+// Entrypoint for the MCP stdio server (`node node_modules/.bin/tsx
+// src/scripts/mcp_server/__main__.ts`). glama launches this file directly
+// via `internal/glama/run`; Claude Desktop / Zed / Continue stdio-server
+// configs point at the same entry through `agent-config mcp:run`. Keep
+// this file flat so crash stack traces point at server.ts, not the
+// bootstrap.
 //
 // `node __main__.js` (or importing this module as the package main) runs
 // the server, mirroring the Python `if __name__ == "__main__": main()`

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -75,7 +75,7 @@
       "name": "memory_signal",
       "description": "Record an engineering-memory signal — a short, anchored observation such as a recurring bug pattern or an ownership note — to the monthly intake log `agents/memory/intake/signals-YYYY-MM.jsonl`. Use to capture a learning tied to a specific file so future `memory_lookup` calls surface it. Appends to the filesystem and is rate-limited per `(type, path)` within a rolling window. Returns the recorded signal.",
       "side_effect": "fs-write",
-      "implemented_on": [],
+      "implemented_on": ["stdio"],
       "input_schema": {
         "type": "object",
         "properties": {
@@ -198,9 +198,9 @@
     },
     {
       "name": "run_tests",
-      "description": "Run the consumer project's test suite via its auto-detected runner (Pest / PHPUnit, Jest / Vitest, pytest, …). Use to verify a change before claiming it works. Shell-bound. Returns the exit code, the runner name, and a structured tail of the output. Pass `filter` or `path` to narrow the run.",
+      "description": "Run the consumer project's vitest test suite under a compiled safety envelope: fixed argv (no shell interpolation), 120s timeout, 64KB output cap per stream. Shell-exec pilot per the 2026-07-07 council cut — vitest projects only; other runners (Pest / PHPUnit, pytest, Jest) return an error until a future council round approves them. Pass `filter` (vitest --testNamePattern) or `path` (in-tree file or directory) to narrow the run. Returns runner, passed, exit_code, timed_out, truncated stdout/stderr, and duration_ms.",
       "side_effect": "shell",
-      "implemented_on": [],
+      "implemented_on": ["stdio"],
       "input_schema": {
         "type": "object",
         "properties": {
@@ -270,6 +270,81 @@
         "required": ["uri"],
         "additionalProperties": false
       }
+    },
+    {
+      "name": "roadmap_progress",
+      "description": "Regenerate `agents/roadmaps-progress.md` from the current checkbox state of every active roadmap. Use after landing roadmap work to keep the dashboard in sync without a shell round-trip. Writes the dashboard file inside the project tree. Set `dry_run: true` to compute counts without writing.",
+      "side_effect": "fs-write",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "dry_run": {"type": "boolean", "default": false, "description": "When true, return the computed dashboard without writing the file."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "roadmap_archive",
+      "description": "Archive every roadmap that has reached `count_open == 0` and was touched on the current branch — `git mv` to `agents/roadmaps/archive/`, migrate inbound references, and regenerate the dashboard. Use as the PR-gate sweep before opening a pull request. Mutates the git index (moves tracked files) but never commits or pushes.",
+      "side_effect": "fs-write",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "capabilities_index",
+      "description": "Regenerate `CAPABILITIES.yaml`, the package's coverage index of skills, rules, commands, and guidelines. Use after adding or removing an artifact to keep the index current. Pass `check: true` to run in read-only CI mode (fails instead of writing on drift).",
+      "side_effect": "fs-write",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "check": {"type": "boolean", "default": false, "description": "When true, run in read-only drift-check mode instead of writing the index."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "doctor_report",
+      "description": "Run the consumer-project doctor diagnostic and return a structured health report (install drift, hook wiring, settings schema, discovery manifest freshness). Use to triage a misbehaving install. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "conformance_check",
+      "description": "Run the consumer conformance contract (`doctor --ci` plus installed-and-firing checks) and return pass/fail per check. Use to verify a consumer project's install is fully wired before relying on it. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "telemetry_report",
+      "description": "Return the artefact-engagement telemetry report — essential / useful / retirement-candidate skills and rules ranked by recorded consult+apply signals over a rolling window. Use to see which artifacts are actually load-bearing. Read-only. No-op (empty report) when telemetry recording is disabled.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "window_days": {"type": "integer", "minimum": 1, "default": 30, "description": "Reporting window in days. Defaults to 30."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "council_estimate",
+      "description": "Estimate the token cost of an AI-council debate over a given input (roadmap, diff, prompt, or file set) without spending — no network call, no billing. Use before deciding whether to authorize a real council run. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "input_path": {"type": "string", "description": "Path to the roadmap, diff, or file to estimate council cost for."},
+          "depth": {"type": "string", "enum": ["shallow", "deep"], "description": "Council depth tier to estimate for. Defaults to the configured default depth."}
+        },
+        "required": ["input_path"],
+        "additionalProperties": false
+      }
     }
   ]
 }