@event4u/agent-config 8.2.0 → 8.3.0

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
+      }
     }
   ]
 }