@geraldmaron/construct 1.4.0 → 1.4.1

package/lib/hooks/guard-bash.mjs

@@ -4,7 +4,9 @@
  *
  * Runs as PreToolUse on Bash. Scans the command against a blocklist of destructive patterns (rm -rf, force push to main, etc.) and exits 2 to block matches.
  *
- * @p95ms 5
+ * Budget covers the role-fence path below — doctorRoot lookup, last-agent file reads, and the lazy manifest/fence/approval imports — which the original 5ms target predated; the nightly bench (variance-heavy CI lane) measured ~17-19ms marginal, so the budget reflects that real cost with the ×2 gate tolerance still catching a true regression.
+ *
+ * @p95ms 15
  * @maxBlockingScope PreToolUse
  *
  * @lifecycle PreToolUse

package/lib/mcp/server.mjs

@@ -1334,7 +1334,7 @@ const ALL_TOOL_DEFS = [
 // host/model; the long tail is reachable, just not front-loaded.
 
 const CORE_TOOL_NAMES = new Set([
-  'orchestration_policy', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
+  'orchestration_policy', 'orchestration_run', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
   'memory_search', 'project_context', 'summarize_diff', 'find_tool',
   'author_artifact', 'document_export', 'publish_run', 'artifact_workflow',
   'workflow_invoke', 'triage_recommend', 'orchestration_readiness',

package/lib/mcp/tools/web-search.mjs

@@ -14,6 +14,24 @@
 const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
 const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
 
+// Recency enforcement (rules/common/research.md §1, research-execution-policy
+// recencyRule). The researcher is told to search most-recent-first and treat
+// sources older than 12 months as stale, but the provider returns relevance- and
+// authority-ranked results with the date dropped, so older established sources
+// surface over newer ones. Normalize a date from whatever field the provider
+// supplies, flag staleness against the 12-month window, and reorder
+// most-recent-first. Admiralty-derived `confidence` is left intact (ADR-0017);
+// recency rides alongside it as `date` + `stale` rather than folded into it.
+
+const STALE_AFTER_DAYS = 365;
+
+function normalizeDate(it) {
+  const raw = it.date || it.publishedAt || it.published || it.published_at || it.datePublished || null;
+  if (!raw) return null;
+  const t = Date.parse(raw);
+  return Number.isNaN(t) ? null : new Date(t).toISOString().slice(0, 10);
+}
+
 function providerConfig(env) {
   const url = env.WEB_SEARCH_URL;
   if (!url) return null;
@@ -49,7 +67,7 @@ function degraded(reason, note) {
   return { source: 'web', degraded: true, degradationReason: reason, results: [], note };
 }
 
-export async function webSearch(args = {}, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
+export async function webSearch(args = {}, { env = process.env, fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
   const { query, claim, recency = null } = args;
   if (!query || typeof query !== 'string') {
     return { error: { code: 'INVALID_INPUT', message: 'query (string) is required' } };
@@ -78,6 +96,8 @@ export async function webSearch(args = {}, { env = process.env, fetchImpl = glob
     .filter((it) => it && typeof it.url === 'string' && /^https?:\/\//.test(it.url))
     .map((it) => {
       const admiralty = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty) ? it.admiralty : 'C3';
+      const date = normalizeDate(it);
+      const stale = date != null && (now - Date.parse(date)) > STALE_AFTER_DAYS * 86_400_000;
       return {
         source: 'web',
         url: it.url,
@@ -86,9 +106,22 @@ export async function webSearch(args = {}, { env = process.env, fetchImpl = glob
         class: classifyResult(it.url),
         admiralty,
         confidence: confidenceFromGrade(admiralty),
+        date,
+        stale,
         needsGrading: !(typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty)),
       };
     });
 
+  // Order most-recent-first: fresh dated results, then undated (provider order
+  // kept by the stable sort), then stale ones; newest first within a tier.
+
+  const tier = (r) => (r.date && !r.stale ? 0 : r.date ? 2 : 1);
+  results.sort((a, b) => {
+    const t = tier(a) - tier(b);
+    if (t !== 0) return t;
+    if (a.date && b.date) return Date.parse(b.date) - Date.parse(a.date);
+    return 0;
+  });
+
   return { source: 'web', degraded: false, query, claim, results, dropped: items.length - results.length };
 }

package/lib/orchestration-policy.mjs

@@ -183,6 +183,38 @@ export function classifyResearchShape(request = '') {
   return null;
 }
 
+// Live web access is distinct from research-shape: a bare "connect to the
+// internet" or "fetch example.com" carries none of the comparative/landscape
+// vocabulary, so without this it falls to the immediate track and the
+// orchestrator — which holds no network tools — refuses instead of dispatching
+// the web-capable cx-researcher. A literal URL, an explicit online/internet
+// phrase, or a fetch/scrape verb paired with a web object is the signal.
+
+const WEB_VERB = '(?:fetch|download|open|load|read|scrape|crawl|retrieve|pull|grab|access|visit|hit|reach)';
+const WEB_OBJECT = '(?:url|link|web\\s?page|web\\s?site|site|page|online|internet|web|endpoint|api)';
+const LIVE_WEB_ACCESS_PATTERNS = [
+  /https?:\/\/\S+/i,
+  /\bwww\.[a-z0-9-]+\.[a-z]{2,}/i,
+  /\b(?:connect|connecting|connection)\s+to\s+the\s+(?:internet|web|network)\b/i,
+  /\binternet\s+(?:access|connection|connectivity)\b/i,
+  /\b(?:go|get|getting|going)\s+online\b/i,
+  /\b(?:browse|browsing|surf)\b[\s\S]{0,20}\b(?:web|internet|site|page|url)\b/i,
+  /\b(?:curl|wget|ping)\b/i,
+  /\b(?:is|are)\b[\s\S]{0,40}\b(?:online|offline|reachable|unreachable|responding)\b/i,
+  new RegExp(`\\b${WEB_VERB}\\b[\\s\\S]{0,40}\\b${WEB_OBJECT}\\b`, 'i'),
+  new RegExp(`\\b${WEB_VERB}\\b[\\s\\S]{0,40}\\b[a-z0-9-]+\\.(?:com|org|net|io|dev|ai|gov|edu|co|app|info|xyz)\\b`, 'i'),
+];
+
+/**
+ * Whether a request needs live external web/network access the orchestrator
+ * cannot perform itself (it is a read-only router with no network tools), so it
+ * must be routed to cx-researcher rather than answered immediately.
+ */
+export function requiresLiveWebAccess(request = '') {
+  const text = String(request);
+  return LIVE_WEB_ACCESS_PATTERNS.some((pattern) => pattern.test(text));
+}
+
 /**
  * Returns whether external research is required before scaffolding, with the
  * reason. Triggered by named entities not in the project glossary, by
@@ -193,6 +225,9 @@ export function requiresExternalResearch({ request = '', workCategory, riskFlags
   const entities = extractNamedEntities(request);
   const category = workCategory ?? classifyWorkCategory(request);
   const flags = riskFlags ?? detectRiskFlags(request);
+  if (requiresLiveWebAccess(request)) {
+    return { required: true, reason: 'web-access' };
+  }
   if (entities.length > 0) {
     return { required: true, reason: 'named-entities', entities };
   }
@@ -507,6 +542,7 @@ export function determineExecutionTrack({
     || isOperationsPlanningRequest(request)
     || isRdLeadRequest(request)
     || isExplorerRequest(request)
+    || requiresLiveWebAccess(request)
   ) {
     return EXECUTION_TRACKS.focused;
   }

package/package.json

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

package/scripts/sync-specialists.mjs

@@ -448,6 +448,13 @@ const standardConstructTools = [
   "cx_trace",
   "cx_score",
 ].join(",");
+
+// The orchestrator's atomic contract is classify-then-dispatch: orchestration_policy
+// then orchestration_run. On allowlist hosts (Claude) these must be named in the
+// agent's tools list or the call is blocked, leaving the orchestrator unable to route.
+// Single source of truth so every host's orchestrator grant stays in parity.
+
+const ORCHESTRATOR_DISPATCH_TOOLS = ["orchestration_policy", "orchestration_run"];
 const managedStart = `# BEGIN ${systemName.toUpperCase()} AGENTS`;
 const managedEnd = `# END ${systemName.toUpperCase()} AGENTS`;
 const mdManagedStart = `<!-- BEGIN ${systemName.toUpperCase()} AGENTS -->`;
@@ -765,7 +772,8 @@ function orchestrationMicroPrompt(platform) {
     `You are the primary orchestrator. Before any non-trivial answer, call \`${policyTool}\` with the user's \`request\`. Do not guess agent names or workflow types.\n\n` +
     `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
     `  call ${policyTool} { "request": "add rate limiting to the API" }\n` +
-    `If the route is focused/orchestrated specialist work, call \`${runTool}\` with the same request. If the route suggests a workflow such as \`research-synthesis\`, pass it as \`workflow_type\`. Do not narrate completed research unless \`${runTool}\` or evidence tools actually ran.`
+    `If the route is focused/orchestrated specialist work, call \`${runTool}\` with the same request. If the route suggests a workflow such as \`research-synthesis\`, pass it as \`workflow_type\`. Do not narrate completed research unless \`${runTool}\` or evidence tools actually ran.\n\n` +
+    `If a request needs a capability you lack — live web/network access, external data, code execution — do not refuse or tell the user to run it themselves. Route it via \`${runTool}\` to the specialist that holds the capability (web access lives with the researcher), or ask one clarifying question when the target is ambiguous.`
   );
 }
 
@@ -984,6 +992,13 @@ function claudeAgentMarkdown(entry, allEntries) {
     ...baseTools.split(",").map((t) => t.trim()),
     ...standardConstructTools.split(","),
   ]);
+
+  // Claude's tools list is a hard allowlist; the orchestrator can only route if its
+  // dispatch tools are named here.
+
+  if (entry.isOrchestrator) {
+    for (const tool of ORCHESTRATOR_DISPATCH_TOOLS) toolSet.add(tool);
+  }
   const tools = Array.from(toolSet).filter(Boolean).join(",");
 
   return `---
@@ -1346,6 +1361,40 @@ When using this prompt, stay within the role above and adapt to the current repo
 `;
 }
 
+// VS Code reads custom agents (the renamed successor to chat modes) from
+// .github/agents/<name>.agent.md, and tool grants must use its namespaced ids:
+// <server>/* for an MCP server's tools, web/fetch for outbound web, search/read
+// for repo awareness. The Claude-format tools in .claude/agents/*.md are not
+// recognized here, so the orchestrator needs its own VS Code agent or it lists
+// in the picker with no usable tools.
+
+const COPILOT_AGENT_TOOLS = [
+  "construct-mcp/*",
+  "web/fetch",
+  "web/githubRepo",
+  "search/codebase",
+  "search/usages",
+  "search/fileSearch",
+  "read/problems",
+  "edit/editFiles",
+];
+
+function copilotAgentFile(entry, allEntries) {
+  const name = adapterName(entry);
+  return `---
+description: ${entry.description}
+name: ${name}
+tools: ${JSON.stringify(COPILOT_AGENT_TOOLS)}
+---
+
+${generatedMarkdownNote}
+
+# ${name}
+
+${buildPrompt(entry, allEntries, "copilot")}
+`;
+}
+
 function syncCopilot(entries, targetDir = null, wants = true) {
   const promptsDir = targetDir
     ? path.join(targetDir, ".github", "prompts")
@@ -1362,15 +1411,20 @@ function syncCopilot(entries, targetDir = null, wants = true) {
     sweepLegacyPrefixedFiles(promptsDir, ".prompt.md", writeEntries.map((e) => `${adapterName(e)}.prompt.md`));
   }
 
-  // VS Code / Copilot agent mode reads the project's `.claude/agents/*.md`
-  // natively (Claude-format custom agents), so Construct does NOT write a
-  // separate `.github/agents/` set — doing so duplicated every agent in the
-  // picker. A pre-existing `.github/agents/` from an earlier sync is swept.
+  // VS Code reads custom agents from `.github/agents/*.agent.md`. The Claude
+  // tool names in `.claude/agents/*.md` are not recognized there, so the front
+  // door ships as a VS Code agent with namespaced tool grants (construct-mcp/*,
+  // web/fetch, search/read) — selecting it in the dropdown then scopes those
+  // tools in. The Claude-format set stays for Claude Code.
 
-  if (targetDir) {
-    const staleAgentsDir = path.join(targetDir, ".github", "agents");
-    if (!DRY_RUN && fs.existsSync(staleAgentsDir)) fs.rmSync(staleAgentsDir, { recursive: true, force: true });
+  const agentsDir = targetDir
+    ? path.join(targetDir, ".github", "agents")
+    : path.join(home, ".github", "agents");
+  if (!DRY_RUN && wants) mkdirp(agentsDir);
+  for (const entry of writeEntries) {
+    writeFile(path.join(agentsDir, `${adapterName(entry)}.agent.md`), copilotAgentFile(entry, entries), { stamp: false });
   }
+  if (fs.existsSync(agentsDir)) removeStaleAdapters(agentsDir, ".agent.md", writeEntries);
 
   const instructionsPath = targetDir
     ? path.join(targetDir, ".github", "copilot-instructions.md")
@@ -1387,7 +1441,7 @@ function syncCopilot(entries, targetDir = null, wants = true) {
   const list = listEntries.map((e) => `- \`${adapterName(e)}\`: use \`${promptPathPrefix}/${adapterName(e)}.prompt.md\`.`).join("\n");
   const note = `## ${systemName.charAt(0).toUpperCase() + systemName.slice(1)} Agent Prompts
 
-For a real multi-specialist run, Copilot agent mode calls the \`orchestration_run\` MCP tool (start the engine with \`construct dashboard\`). The prompts below are reusable role profiles for single-pass work:
+Select \`${systemName}\` from the chat mode dropdown to enter the orchestrator: describe an outcome and it classifies the request and dispatches the right specialists through the \`construct-mcp\` tools (\`orchestration_policy\` then \`orchestration_run\`). You ask for outcomes, not specialists — it routes internally. Requires the \`construct-mcp\` server (wired in \`.vscode/mcp.json\`); if its tools are unavailable, the mode cannot route and will say so rather than guess.
 
 ${list || "(no front-door prompts to surface)"}`;
 
@@ -1432,6 +1486,45 @@ function getVSCodeUserMcpPaths() {
     .filter((file) => fs.existsSync(file));
 }
 
+// A merged mcp.json preserves existing entries so user customizations survive a
+// re-sync. A construct-owned server path is a fully-resolved, non-placeholder
+// path, so the preserve rule keeps it even when it points at a different toolkit
+// root than the current one — and VS Code then launches a server that may not
+// exist. Treat a construct toolkit path outside the current root as stale so the
+// sync refreshes it; user-owned servers carry no lib/mcp toolkit path and stay.
+
+export function mcpEntryPointsOutsideToolkit(entry, root) {
+  const args = Array.isArray(entry?.args) ? entry.args : [];
+  return args.some(
+    (arg) => typeof arg === "string"
+      && /\/lib\/mcp\/[a-z0-9-]+\.mjs$/.test(arg)
+      && !arg.startsWith(`${root}/`),
+  );
+}
+
+// VS Code scans both `.github/agents` and `.claude/agents`, so the orchestrator
+// would list twice — once with VS Code tools (.github/agents) and once with
+// Claude tool names VS Code ignores (.claude/agents). `chat.agentFilesLocations`
+// is the documented lever to pin the scan; its power over the built-in
+// `.claude/agents` compatibility scan is version-dependent, so this is a
+// best-effort hint, not a guarantee. Merge only into a strictly-parseable file
+// and never overwrite an existing choice, so a commented (JSONC) or
+// user-customized settings.json is left untouched.
+
+export function pinVscodeAgentLocations(targetDir) {
+  if (DRY_RUN) return;
+  const settingsPath = path.join(targetDir, ".vscode", "settings.json");
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")) || {}; }
+    catch { return; }
+  }
+  if (settings["chat.agentFilesLocations"]) return;
+  settings["chat.agentFilesLocations"] = { ".github/agents": true, ".claude/agents": false };
+  mkdirp(path.dirname(settingsPath));
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+
 function syncVSCode(targetDir = null, wants = true) {
   const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   if (Object.keys(registryMcp).length === 0) return false;
@@ -1480,13 +1573,15 @@ function syncVSCode(targetDir = null, wants = true) {
       const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
       const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
       const transportMismatch = registryWantsCommand && existingIsRemote;
-      if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
+      const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
+      if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
       config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
     }
     if (!DRY_RUN) {
       mkdirp(path.dirname(mcpPath));
       fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
     }
+    pinVscodeAgentLocations(targetDir);
     return true;
   }
 
@@ -1504,7 +1599,8 @@ function syncVSCode(targetDir = null, wants = true) {
         const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
         const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
         const transportMismatch = registryWantsCommand && existingIsRemote;
-        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
+        const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
+        if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
         config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
       }
       if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");