@geraldmaron/construct 1.0.24 → 1.1.0

package/lib/telemetry/hook-calls.mjs

@@ -0,0 +1,138 @@
+/**
+ * lib/telemetry/hook-calls.mjs — measure which hooks fire and which actually block.
+ *
+ * Hooks carry @p95ms latency budgets but no record of how often each one fires or
+ * blocks, so a hook that gates real mistakes and one that has never fired once look
+ * identical. The central dispatcher (`construct hook <name>`) appends one JSON line
+ * per invocation to ~/.cx/hook-calls.jsonl with the hook id, the outcome derived
+ * from its exit code, and latency, so `construct hooks:usage` can answer which hooks
+ * earn their keep before any are consolidated.
+ *
+ * Outcome is what the dispatcher can observe centrally: exit 0 = ok, exit 2 = blocked
+ * (the Claude Code convention for a refused tool call — see block-no-verify), any
+ * other non-zero = error. A hook that mutates state without blocking reads as `ok`
+ * here; per-hook mutation reporting is a separate, opt-in signal.
+ *
+ * Disable with CONSTRUCT_HOOK_TELEMETRY=off. Errors here are non-fatal — telemetry
+ * must never change a hook's exit code or add a failure mode to the hot path.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScope } from '../project-root.mjs';
+import { cxDir } from '../paths.mjs';
+
+// cxDir() (not os.homedir()) so CX_HOME_OVERRIDE isolates the log in tests and the
+// path stays consistent with the rest of ~/.cx. Resolved per-call so an override
+// set after import still takes effect.
+
+export function defaultLogPath() {
+  return path.join(cxDir(), 'hook-calls.jsonl');
+}
+
+// Exit-code → outcome, using the Claude Code hook convention (2 = block a tool
+// call). Anything else non-zero is a hook that errored rather than deliberately
+// gated, which is itself a value signal (a hook erroring every fire is noise).
+
+export function outcomeFromExit(code) {
+  if (code === 0 || code == null) return 'ok';
+  if (code === 2) return 'blocked';
+  return 'error';
+}
+
+/**
+ * Fire-and-forget log of one hook invocation.
+ *
+ * @param {object} event
+ * @param {string} event.hookId — the hook name, e.g. "block-no-verify"
+ * @param {number} [event.exitCode] — the hook's process exit code
+ * @param {'ok'|'blocked'|'error'} [event.outcome] — derived from exitCode if omitted
+ * @param {number} [event.latencyMs]
+ * @param {object} [opts]
+ * @param {string} [opts.logPath]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ */
+export function logHookCall(event, opts = {}) {
+  const env = opts.env || process.env;
+  if (env.CONSTRUCT_HOOK_TELEMETRY === 'off') return;
+  if (!event || !event.hookId) return;
+
+  const logPath = opts.logPath || defaultLogPath();
+  const outcome = event.outcome || outcomeFromExit(event.exitCode);
+  const scope = resolveProjectScope();
+  const entry = {
+    ts: new Date().toISOString(),
+    hookId: event.hookId,
+    outcome,
+    ...(event.exitCode != null ? { exitCode: event.exitCode } : {}),
+    ...(scope?.projectId ? { projectId: scope.projectId } : {}),
+    ...(event.latencyMs != null ? { latencyMs: event.latencyMs } : {}),
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    appendBounded('hook-calls', logPath, JSON.stringify(entry) + '\n');
+  } catch {
+    // Append-only telemetry; an unwritable home dir is a silent skip rather than
+    // a new failure mode on the hook that triggered the call.
+  }
+}
+
+/**
+ * Roll a hook-calls log up into per-hook stats: fire count, blocked/error counts,
+ * most-recent timestamp, latency percentiles. A hook with calls but zero blocks/
+ * errors over a long window is a pure observer — a demotion candidate.
+ */
+export function summarizeHookCalls({ logPath = defaultLogPath(), since } = {}) {
+  if (!fs.existsSync(logPath)) return { totalEvents: 0, hooks: {} };
+  const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean);
+  const sinceTs = since ? _parseSince(since) : null;
+  const hooks = {};
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (!entry?.hookId) continue;
+    if (sinceTs && entry.ts && entry.ts < sinceTs) continue;
+    const slot = hooks[entry.hookId] ||= { calls: 0, blocked: 0, errors: 0, latencies: [], lastCalledAt: null };
+    slot.calls += 1;
+    if (entry.outcome === 'blocked') slot.blocked += 1;
+    if (entry.outcome === 'error') slot.errors += 1;
+    if (entry.latencyMs != null) slot.latencies.push(entry.latencyMs);
+    if (entry.ts && (!slot.lastCalledAt || entry.ts > slot.lastCalledAt)) slot.lastCalledAt = entry.ts;
+  }
+  const result = {};
+  for (const [id, slot] of Object.entries(hooks)) {
+    result[id] = {
+      calls: slot.calls,
+      blocked: slot.blocked,
+      errors: slot.errors,
+      lastCalledAt: slot.lastCalledAt,
+      ...(slot.latencies.length ? _latencyStats(slot.latencies) : {}),
+    };
+  }
+  return { totalEvents: lines.length, hooks: result };
+}
+
+/**
+ * Hooks with zero fire events in the window — they cost a settings entry and a
+ * spawn budget but have never run, so they are consolidation candidates.
+ */
+export function findIdleHooks({ logPath = defaultLogPath(), since = '30d', allHookIds = [] } = {}) {
+  const { hooks } = summarizeHookCalls({ logPath, since });
+  const active = new Set(Object.keys(hooks));
+  return allHookIds.filter((id) => !active.has(id));
+}
+
+function _parseSince(since) {
+  const m = String(since).match(/^(\d+)(d|h|m)$/);
+  if (!m) return null;
+  const ms = parseInt(m[1], 10) * ({ d: 86400000, h: 3600000, m: 60000 }[m[2]]);
+  return new Date(Date.now() - ms).toISOString();
+}
+
+function _latencyStats(arr) {
+  const sorted = [...arr].sort((a, b) => a - b);
+  const p = (pct) => sorted[Math.floor((pct / 100) * (sorted.length - 1))];
+  return { p50LatencyMs: p(50), p95LatencyMs: p(95) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.24",
+  "version": "1.1.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",

package/personas/construct.md

@@ -62,7 +62,7 @@ The active profile (`construct profile show`) sets the intake taxonomy. Session-
 
 Lead with the answer. One question when blocked. Confirm what changed when done.
 
-**Output style**: format human-facing output (terminal, prose, dashboard) for neurodivergent readers — answer first, clear hierarchy, scannable chunks, plain language, explicit next step; never rely on color or motion alone; honor `NO_COLOR` and reduced-motion. Presentation only — never reshape machine-readable output (`--json`, parsed tokens, registries, contracts). See `rules/common/neurodivergent-output.md`.
+**Output style**: format human-facing output (terminal, prose, dashboard) for neurodivergent readers — answer first, clear hierarchy, plain language, explicit next step. Prose for reasoning; lists only for genuinely parallel items where scanning helps, never a wall of bullets. Never rely on color or motion alone; honor `NO_COLOR` and reduced-motion. Presentation only — never reshape machine-readable output (`--json`, parsed tokens, registries, contracts). See `rules/common/neurodivergent-output.md`.
 
 **Tool invisibility**: deliverables are about the user's project, never Construct. Never name Construct, `cx-*` role ids, or internal orchestration mechanics in artifact content unless the subject project is Construct itself. Provenance goes in a comment, not the prose. See `rules/common/tool-invisibility.md`.
 

package/platforms/capabilities.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "../schemas/platform-capabilities.schema.json",
+  "version": 1,
+  "hosts": {
+    "claude": {
+      "displayName": "Claude Code",
+      "hasNativeSubagents": false,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": {
+        "supported": true,
+        "globalAllowlist": [
+          "pre:bash:block-no-verify",
+          "pre:bash:guard-dangerous",
+          "pre:edit:config-protection",
+          "pre:edit-guard",
+          "post:edit:json-validate",
+          "post:edit:scan-secrets"
+        ]
+      },
+      "globalMcpAllowlist": ["context7"]
+    },
+    "codex": {
+      "displayName": "Codex",
+      "hasNativeSubagents": false,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "toml",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "copilot": {
+      "displayName": "Copilot",
+      "hasNativeSubagents": false,
+      "instructionsOnly": true,
+      "supportsMcp": false,
+      "configFormat": "markdown",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "opencode": {
+      "displayName": "OpenCode",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "modelfile",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "vscode": {
+      "displayName": "VS Code",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "cursor": {
+      "displayName": "Cursor",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    }
+  }
+}

package/platforms/opencode/sync-config.mjs

@@ -1,13 +1,51 @@
 #!/usr/bin/env node
 /**
- * sync-config.mjs — Fetch free models from OpenRouter and sync into OpenCode config.
- * Run periodically or during install to keep the free model list current.
+ * sync-config.mjs — Fetch free models from OpenRouter and local models from Ollama,
+ * and sync into OpenCode config.
  */
 import fs from "node:fs";
-import { readOpenCodeConfig, writeOpenCodeConfig, findOpenCodeConfigPath } from "../lib/opencode-config.mjs";
+import { spawnSync } from "node:child_process";
+import { readOpenCodeConfig, writeOpenCodeConfig, findOpenCodeConfigPath } from "../../lib/opencode-config.mjs";
+import { ensureLocalContextVariants, modelDigest } from "../../lib/ollama/provision-context.mjs";
+import { isKnownCollapsed } from "../../lib/ollama/capability-store.mjs";
+
+const LOCAL_NUM_CTX = Number(process.env.CONSTRUCT_LOCAL_NUM_CTX) || 32768;
 
 const configPath = findOpenCodeConfigPath();
 
+async function fetchLocalOllamaModels() {
+  try {
+    const r = spawnSync("ollama", ["list"], { encoding: "utf8" });
+    if (r.status !== 0) return [];
+    
+    const lines = r.stdout.trim().split("\n").slice(1);
+    const models = lines.map(line => {
+      const parts = line.split(/\s+/).filter(Boolean);
+      const id = parts[0];
+      const size = parts[2];
+      return { id, name: id, size };
+    });
+
+    // Identify redundant tags (same family, many tags)
+    const familyMap = new Map();
+    for (const m of models) {
+      const family = m.id.split(":")[0];
+      if (!familyMap.has(family)) familyMap.set(family, []);
+      familyMap.get(family).push(m);
+    }
+
+    for (const [family, tags] of familyMap) {
+      if (tags.length > 2) {
+        console.log(`[cleanup] Potential redundant tags for ${family}: ${tags.map(t => t.id).join(", ")}`);
+      }
+    }
+
+    return models;
+  } catch {
+    return [];
+  }
+}
+
 async function fetchFreeModels() {
   try {
     const res = await fetch("https://openrouter.ai/api/v1/models");
@@ -31,39 +69,97 @@ async function main() {
 
   const { config } = readOpenCodeConfig();
   const freeModels = await fetchFreeModels();
+  const localModels = await fetchLocalOllamaModels();
 
-  if (freeModels.length === 0) {
-    console.log("No free models fetched. Config unchanged.");
+  if (freeModels.length === 0 && localModels.length === 0) {
+    console.log("No models fetched. Config unchanged.");
     return;
   }
 
   if (!config.provider) config.provider = {};
-  if (!config.provider.openrouter) {
-    config.provider.openrouter = {
-      npm: "@ai-sdk/openai-compatible",
-      name: "OpenRouter",
-      options: {
-        baseURL: "https://openrouter.ai/api/v1",
-        headers: {}
-      },
-      models: {}
-    };
+  
+  // Sync OpenRouter Free Models
+  if (freeModels.length > 0) {
+    if (!config.provider.openrouter) {
+      config.provider.openrouter = {
+        npm: "@ai-sdk/openai-compatible",
+        name: "OpenRouter",
+        options: {
+          baseURL: "https://openrouter.ai/api/v1",
+          headers: {}
+        },
+        models: {}
+      };
+    }
+    const existingOR = config.provider.openrouter.models ?? {};
+    for (const model of freeModels) {
+      const cleanName = model.name.replace(/\s*\(free\)/gi, "").trim();
+      existingOR[model.id] = { name: `[free] ${cleanName}` };
+    }
+    config.provider.openrouter.models = Object.fromEntries(
+      Object.entries(existingOR).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
+    );
   }
 
-  const existingModels = config.provider.openrouter.models ?? {};
-  const merged = { ...existingModels };
-  for (const model of freeModels) {
-    if (!merged[model.id]) {
-      merged[model.id] = { name: `${model.name} (free)` };
+  // Sync Local Ollama Models
+  if (localModels.length > 0) {
+    if (!config.provider.ollama) {
+      config.provider.ollama = {
+        npm: "@ai-sdk/openai-compatible",
+        name: "Ollama",
+        options: {
+          baseURL: "http://localhost:11434/v1"
+        },
+        models: {}
+      };
     }
-  }
+    // A raw model runs at Ollama's 4096 default over the /v1 path, which a Construct
+    // session's tool schemas overrun. Provision a context-extended Modelfile variant
+    // for each tool-capable model lacking a baked num_ctx (any size — capability does
+    // not track size) and register the variant in place of the raw tag so the model
+    // OpenCode actually talks to has a real context window.
+
+    const { mapping: variantMap, actions } = ensureLocalContextVariants({ numCtx: LOCAL_NUM_CTX });
+    for (const a of actions) {
+      if (a.action === "created" || a.action === "would-create") console.log(`[ollama] context variant ${a.action}: ${a.variant} (num_ctx ${LOCAL_NUM_CTX})`);
+    }
+
+    const existingLocal = config.provider.ollama.models ?? {};
+    for (const model of localModels) {
+      const registerId = variantMap[model.id] || model.id;
+      // Register the context-extended variant in place of the raw tag so the model
+      // picker surfaces the windowed option, not the one Ollama serves at 4096.
 
-  config.provider.openrouter.models = Object.fromEntries(
-    Object.entries(merged).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
-  );
+      if (registerId !== model.id) delete existingLocal[model.id];
+      existingLocal[registerId] = {
+        name: registerId.replace(/\s*\(local\)/gi, "").trim(),
+        family: registerId.includes("qwen") ? "qwen2" : "llama",
+        tool_call: true
+      };
+
+      // Capability honesty: a model the probe recorded as COLLAPSED (digest still
+      // matching) word-salads on the agentic loop. Warn rather than hide — the
+      // user keeps the choice and can re-probe — so a stale or false verdict never
+      // silently strands a working model.
+      if (isKnownCollapsed(model.id, modelDigest(model.id))) {
+        console.log(`[ollama] WARNING: ${model.id} probed COLLAPSED — not agentic-capable. Re-probe: construct doctor --probe-local`);
+      }
+    }
+    config.provider.ollama.models = Object.fromEntries(
+      Object.entries(existingLocal).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
+    );
+
+    // Agentic coherence is model-specific and not predictable from size: some small
+    // coder models collapse into repetition on an agentic system prompt while others
+    // run the same Construct payload cleanly. Surface the empirical probe rather than
+    // silently registering a model that will produce word salad.
+
+    console.log("[ollama] Verify a model handles agentic prompts before relying on it:");
+    console.log("[ollama]   node lib/ollama/provision-context.mjs --probe --model=<id>");
+  }
 
   writeOpenCodeConfig(config, configPath);
-  console.log(`Synced ${freeModels.length} free models from OpenRouter.`);
+  console.log(`Synced ${freeModels.length} free models and ${localModels.length} local models.`);
 }
 
 main();

package/rules/common/neurodivergent-output.md

@@ -28,7 +28,7 @@ Use headings in order (H2, then H3) and do not skip or nest deeper. One `h1`-equ
 
 ## 3. Scannable chunks
 
-Short paragraphs. Bulleted or numbered lists in place of long sentences that pack several facts together. White space between sections. Prefer three short lines over one dense one.
+Short paragraphs with white space between sections; prefer three short lines over one dense one. Use a bulleted or numbered list for genuinely parallel items — a set of options, steps, or independent facts — where scanning is the point. Keep reasoning, cause-and-effect, and narrative in prose: a wall of bullets fragments the logic that connects the points and is harder to follow, not easier. Bullets for what scans, sentences for what reasons.
 
 ## 4. Plain, literal language
 

package/rules/web/coding-style.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web coding style rule. Use when writing or reviewing web code that involves coding style.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/coding-style.md](../common/coding-style.md) with web-specific frontend content.
 

package/rules/web/design-quality.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web design quality rule. Use when writing or reviewing web code that involves design quality.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/patterns.md](../common/patterns.md) with web-specific design-quality guidance.
 

package/rules/web/hooks.md

@@ -1,5 +1,13 @@
 ---
 description: Prefer project-local tooling.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 # Web Hooks
 

package/rules/web/patterns.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web patterns rule. Use when writing or reviewing web code that involves patterns.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/patterns.md](../common/patterns.md) with web-specific patterns.
 

package/rules/web/performance.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web performance rule. Use when writing or reviewing web code that involves performance.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/performance.md](../common/performance.md) with web-specific performance content.
 

package/rules/web/security.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web security rule. Use when writing or reviewing web code that involves security.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/security.md](../common/security.md) with web-specific security content.
 

package/rules/web/testing.md

@@ -1,5 +1,13 @@
 ---
 description: Construct web testing rule. Use when writing or reviewing web code that involves testing.
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/*.svelte"
 ---
 > This file extends [common/testing.md](../common/testing.md) with web-specific testing content.