@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/mcp/tool-budget.mjs

@@ -8,15 +8,20 @@
  *   2. which external MCP servers are `enabled` in opencode.json — sync disables
  *      the heavy ones for local-capable setups (they cannot be trimmed at runtime).
  * Holds the shared token-sizing helper and the external-server id list both
- * levers reason about.
+ * levers reason about, plus the owned-loop tool-budget filter that trims the
+ * Vercel AI SDK tool set to a compiled execution policy's allowed groups and
+ * schema cap (lib/models/execution-policy.mjs).
  */
 
+import { getMeasuredHeavyExternalMcpTokenCost } from './external-schema-cost.mjs';
+
 const TOKENS_PER_CHAR = 0.25;
 
 // Heavy external MCP servers Construct registers globally. On a local-capable
-// setup these alone serialize ~12k tokens into every agent's window (including
-// the built-in Build/Plan agents) and cannot be filtered per request, so sync
-// disables them in opencode.json. construct-mcp's own knowledge_search /
+// setup these serialize a measured ~37k tokens of tool schema into every agent's
+// window (github alone ~30k as of 2026-06-22; see tests/fixtures/mcp-tool-schemas/
+// and scripts/measure-external-mcp-schemas.mjs) and cannot be filtered per request,
+// so sync disables them in opencode.json. construct-mcp's own knowledge_search /
 // memory_search cover the search/memory cases.
 
 export const HEAVY_EXTERNAL_MCP_IDS = ['context7', 'github', 'memory', 'sequential-thinking', 'playwright'];
@@ -29,6 +34,7 @@ export const LOCAL_SURFACE_MODES = ['auto', 'on', 'off'];
 
 export function isLocalModel(model) {
   const m = (model || "").toLowerCase();
+  if (m.startsWith("local/")) return true;
   return m.includes("ollama") || m.includes("localhost") || m.includes("127.0.0.1");
 }
 
@@ -51,3 +57,48 @@ export function estimateToolTokens(tools) {
   const arr = Array.isArray(tools) ? tools : Object.values(tools);
   return Math.round(JSON.stringify(arr).length * TOKENS_PER_CHAR);
 }
+
+export { getMeasuredHeavyExternalMcpTokenCost };
+
+// Maps the owned loop's agent tool names (apps/chat/engine/tools/registry.mjs)
+// onto the execution-policy tool groups (lib/models/execution-policy.mjs) so a
+// compiled policy can trim the serialized tool surface for a capability-
+// constrained model. construct_tool is the single MCP gateway, so it stands in
+// for the whole 'construct' group. An unrecognized name falls back to
+// 'construct' — a group present in every tier — so an unclassified tool is never
+// silently dropped from a constrained surface.
+
+const AGENT_TOOL_GROUPS = Object.freeze({
+  read: 'read',
+  glob: 'search',
+  grep: 'search',
+  write: 'edit',
+  edit: 'edit',
+  shell: 'shell',
+  construct_tool: 'construct',
+});
+
+export function toolGroupForName(name) {
+  return AGENT_TOOL_GROUPS[name] || 'construct';
+}
+
+// Trim a tool set to the compiled policy's envelope: drop any tool whose group is
+// outside allowedToolGroups, then cap the survivors at maxToolSchemas in stable
+// insertion order. A null allowedToolGroups means "no group filter" and an
+// unbounded cap means "no count limit", so the rich/hosted-direct envelope (all
+// groups, cap 32) returns the input set unchanged.
+
+export function applyToolBudget(tools, { allowedToolGroups = null, maxToolSchemas = Infinity } = {}) {
+  if (!tools || typeof tools !== 'object') return tools;
+  const allow = Array.isArray(allowedToolGroups) ? new Set(allowedToolGroups) : null;
+  const cap = Number.isFinite(maxToolSchemas) ? Math.max(0, Math.floor(maxToolSchemas)) : Infinity;
+  const out = {};
+  let kept = 0;
+  for (const [name, def] of Object.entries(tools)) {
+    if (allow && !allow.has(toolGroupForName(name))) continue;
+    if (kept >= cap) break;
+    out[name] = def;
+    kept += 1;
+  }
+  return out;
+}

package/lib/mcp/tools/document.mjs

@@ -1,17 +1,31 @@
 /**
  * lib/mcp/tools/document.mjs — Document-handling MCP tools: extract text, ingest, infer schema, list schema artifacts.
  *
- * All functions are async-safe; extractDocumentText and listSchemaArtifactsTool are synchronous.
+ * All functions are async-safe; listSchemaArtifactsTool is synchronous.
  * Depends on lib/document-extract.mjs, lib/document-ingest.mjs, lib/schema-infer.mjs, lib/schema-artifact.mjs.
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { extractDocumentText as extractLocalDocumentText } from '../../document-extract.mjs';
+import {
+  extractDocumentTextAsync,
+  extractDocumentTextNodeNative,
+} from '../../document-extract.mjs';
 import { ingestDocuments } from '../../document-ingest.mjs';
 import { inferDocumentSchema, inferUnifiedSchema } from '../../schema-infer.mjs';
 import { writeSchemaArtifact, listSchemaArtifacts, SCHEMA_DIR } from '../../schema-artifact.mjs';
 
-export function extractDocumentText(args) {
+async function extractViaIngestPipeline(filePath, { maxChars }) {
+  try {
+    return await extractDocumentTextNodeNative(filePath, { maxChars });
+  } catch (err) {
+    if (err.code === 'OFFICE_REQUIRES_DOCLING' || err.code === 'PDF_REQUIRES_DOCLING') {
+      return extractDocumentTextAsync(filePath, { maxChars });
+    }
+    throw err;
+  }
+}
+
+export async function extractDocumentText(args) {
   const filePath = resolve(String(args.file_path || ''));
   const maxChars = Number.isFinite(Number(args.max_chars)) && Number(args.max_chars) > 0
     ? Math.min(Number(args.max_chars), 200_000)
@@ -22,7 +36,7 @@ export function extractDocumentText(args) {
   }
 
   try {
-    const extracted = extractLocalDocumentText(filePath, { maxChars });
+    const extracted = await extractViaIngestPipeline(filePath, { maxChars });
     return {
       file_path: extracted.filePath,
       extension: extracted.extension,

package/lib/mcp/tools/skills.mjs

@@ -8,9 +8,17 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { routeRequest, routeRequestVerified, requiresExecutiveApproval, TERMINAL_STATES } from '../../orchestration-policy.mjs';
+import {
+  buildConstructToOrchestratorPacket,
+  routeRequest,
+  routeRequestVerified,
+  requiresExecutiveApproval,
+  TERMINAL_STATES,
+} from '../../orchestration-policy.mjs';
 import { buildTaskPacketFromIntent } from '../../workflow-state.mjs';
 import { logSkillCall } from '../../telemetry/skill-calls.mjs';
+import { templateMetadata } from '../../artifact-manifest.mjs';
+import { buildSpecialistCatalog } from '../../specialists/roster.mjs';
 
 export function listSkills({ ROOT_DIR }) {
   const skillsDir = join(ROOT_DIR, 'skills');
@@ -120,14 +128,21 @@ export function getTemplate(args, { ROOT_DIR }) {
   ];
   for (const { source, path: p } of candidates) {
     if (existsSync(p)) {
-      return { source, path: p, content: readFileSync(p, 'utf8') };
+      const meta = templateMetadata(safe, { cwd, rootDir: ROOT_DIR });
+      return { source, path: p, content: readFileSync(p, 'utf8'), metadata: meta };
     }
   }
   return { error: `Template not found: ${safe}`, available: listTemplatesRaw({ ROOT_DIR }) };
 }
 
 export function listTemplates({ ROOT_DIR }) {
-  return listTemplatesRaw({ ROOT_DIR });
+  const raw = listTemplatesRaw({ ROOT_DIR });
+  const cwd = process.cwd();
+  const metadata = {};
+  for (const name of [...new Set([...raw.shipped, ...raw.overridden])]) {
+    metadata[name] = templateMetadata(name, { cwd, rootDir: ROOT_DIR });
+  }
+  return { ...raw, metadata };
 }
 
 export async function agentContract(args = {}) {
@@ -171,6 +186,18 @@ export async function orchestrationPolicy(args) {
   const draftTask = route.track !== 'immediate'
     ? buildTaskPacketFromIntent(args?.request || '', { fileCount: args?.fileCount, moduleCount: args?.moduleCount })
     : null;
+  const handoffPacket = route.track !== 'immediate'
+    ? buildConstructToOrchestratorPacket({
+      request: args?.request || '',
+      route,
+      goal: args?.goal,
+      acceptanceCriteria: args?.acceptanceCriteria,
+      fileCount: args?.fileCount,
+      moduleCount: args?.moduleCount,
+      introducesContract: args?.introducesContract,
+      explicitDrive: args?.explicitDrive,
+    })
+    : null;
 
   // Per-specialist context packets: when the caller supplied a candidate
   // artifact list, build the role-filtered bundle each specialist should
@@ -249,9 +276,11 @@ export async function orchestrationPolicy(args) {
 
   return {
     ...route,
+    specialistCatalog: buildSpecialistCatalog(),
     approvalRequired,
     terminalStates: TERMINAL_STATES,
     draftTask,
+    handoffPacket,
     ...(contextPackets ? { contextPackets } : {}),
     ...(taskGraph ? { taskGraph } : {}),
     ...(intakeError ? { intakeError } : {}),

package/lib/mcp/tools/workflow.mjs

@@ -115,11 +115,23 @@ export function workflowValidate(args) {
  */
 export async function workflowContractValidate(args) {
   const { validateHandoff } = await import('../../contracts/validate.mjs');
+  const { enrichConstructOrchestratorHandoff } = await import('../../contracts/construct-handoff.mjs');
+  const contractId = args.id
+    ?? (args.producer === 'construct' && args.consumer === 'cx-orchestrator' ? 'construct-to-orchestrator' : null);
+  let artifact = args.artifact;
+  if (contractId === 'construct-to-orchestrator' && artifact && typeof artifact === 'object') {
+    artifact = enrichConstructOrchestratorHandoff(artifact, {
+      request: args.request,
+      fileCount: args.fileCount,
+      moduleCount: args.moduleCount,
+      introducesContract: args.introducesContract,
+    });
+  }
   return validateHandoff({
     producer: args.producer,
     consumer: args.consumer,
     id: args.id,
-    artifact: args.artifact,
+    artifact,
     packet: args.packet,
     enforcement: args.enforcement || 'block',
   });

package/lib/model-free-selector.mjs

@@ -62,6 +62,7 @@ export async function pollFreeModels(apiKey) {
       (m) =>
         m?.pricing?.prompt === "0" && m?.pricing?.completion === "0"
     )
+    .filter(isTextOutputModel)
     .map((m) => ({
       id: `openrouter/${m.id}`,
       name: m.name ?? m.id,
@@ -72,6 +73,23 @@ export async function pollFreeModels(apiKey) {
   return models.sort((a, b) => score(b, "standard") - score(a, "standard"));
 }
 
+// A coding/chat tier must emit text; image-generation models (output modality
+// "image") are never valid tier defaults. OpenRouter reports modalities under
+// `architecture`; absent metadata is treated as text so unknown models are not
+// dropped. Vision models (image INPUT, text OUTPUT) remain eligible.
+
+export function isTextOutputModel(model = {}) {
+  const arch = model.architecture || {};
+  let output = arch.output_modalities;
+  if (!Array.isArray(output) && typeof arch.modality === "string" && arch.modality.includes("->")) {
+    output = arch.modality.split("->")[1].split("+").map((s) => s.trim());
+  }
+  if (Array.isArray(output) && output.length) {
+    return output.includes("text") && !output.includes("image");
+  }
+  return true;
+}
+
 /**
  * Score a model for a given tier (higher is better).
  * @param {object} model – Model object as returned by `pollFreeModels`.

package/lib/model-registry.mjs

@@ -1,233 +1,17 @@
 /**
- * lib/model-registry.mjs — Single source of truth for model tier resolution.
+ * lib/model-registry.mjs — compatibility re-exports for model tier resolution.
  *
- * Addresses model tier complexity by:
- * 1. ONE resolution path with clear precedence
- * 2. Validated at config time, not runtime
- * 3. Simple env-only overrides for emergencies
- * 4. Clear error messages when config is missing
+ * Canonical implementation lives in lib/model-router.mjs. This module keeps
+ * the legacy import path stable while CONSTRUCT_MODEL_* env aliases remain
+ * supported for one release cycle via normalizeEnvAssignments in the router.
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-
-// ---------------------------------------------------------------------------
-// Configuration precedence (single source of truth)
-// ---------------------------------------------------------------------------
-
-/**
- * RESOLUTION ORDER (highest to lowest):
- * 1. Environment variables (CX_MODEL_*): Emergency overrides
- * 2. User config (~/.construct/config.env): Personal defaults
- * 3. Registry (specialists/registry.json): Project recommendations
- *
- * Construct ships with NO implicit model defaults (ADR-0027,
- * tests/model-router-no-defaults.test.mjs). When none of the three sources
- * resolves a tier, that tier returns null with source 'not configured'.
- * Callers must surface a clear remediation hint rather than silently
- * substituting a vendor-specific default.
- */
-
-const ENV_PREFIX = 'CX_MODEL';
-
-// ---------------------------------------------------------------------------
-// Core resolution function
-// ---------------------------------------------------------------------------
-
-export function resolveModelTiers(options = {}) {
-  const { 
-    env = process.env,
-    registryPath = null,
-    strict = false,  // If true, require all tiers to be configured
-  } = options;
-  
-  const result = {
-    reasoning: null,
-    standard: null,
-    fast: null,
-  };
-  
-  const sources = {};
-  const errors = [];
-  
-  for (const tier of ['reasoning', 'standard', 'fast']) {
-    const envKey = `${ENV_PREFIX}_${tier.toUpperCase()}`;
-    
-    // Environment variable (highest priority)
-    if (env[envKey]) {
-      result[tier] = env[envKey];
-      sources[tier] = 'env';
-      continue;
-    }
-    
-    // User config (read from env which was loaded by env-config)
-    const configKey = `CONSTRUCT_MODEL_${tier.toUpperCase()}`;
-    if (env[configKey]) {
-      result[tier] = env[configKey];
-      sources[tier] = 'config';
-      continue;
-    }
-    
-    // Registry
-    if (registryPath && fs.existsSync(registryPath)) {
-      try {
-        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-        const registryModel = registry.models?.[tier]?.primary;
-        if (registryModel) {
-          result[tier] = registryModel;
-          sources[tier] = 'registry';
-          continue;
-        }
-      } catch (error) {
-        errors.push(`Failed to read registry: ${error.message}`);
-      }
-    }
-    
-    // No source resolved this tier — leave null + 'not configured' so callers
-    // can surface a clear remediation hint. Aligns with the wired path
-    // (lib/model-router.mjs:resolveTierAssignments) and the no-defaults
-    // contract locked in by tests/model-router-no-defaults.test.mjs.
-
-    result[tier] = null;
-    sources[tier] = 'not configured';
-  }
-
-  const configured = Object.values(result).filter(Boolean).length;
-
-  if (strict && configured < 3) {
-    const missing = Object.entries(result)
-      .filter(([, v]) => !v)
-      .map(([k]) => k);
-    errors.push(`Missing configuration for tiers: ${missing.join(', ')}`);
-  }
-
-  return {
-    models: result,
-    sources,
-    configured,
-    complete: configured === 3,
-    errors: errors.length > 0 ? errors : null,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Quick access helpers
-// ---------------------------------------------------------------------------
-
-export function getModelForTier(tier, options = {}) {
-  const resolved = resolveModelTiers(options);
-  return resolved.models[tier];
-}
-
-export function getModelSource(tier, options = {}) {
-  const resolved = resolveModelTiers(options);
-  return resolved.sources[tier] || 'unknown';
-}
-
-// ---------------------------------------------------------------------------
-// Configuration helpers
-// ---------------------------------------------------------------------------
-
-export function validateModelTiers(options = {}) {
-  const resolved = resolveModelTiers({ ...options, strict: true });
-  const unconfigured = Object.entries(resolved.sources)
-    .filter(([, source]) => source === 'not configured')
-    .map(([tier]) => tier);
-
-  return {
-    valid: resolved.complete && !resolved.errors,
-    errors: resolved.errors,
-    warnings: unconfigured.length > 0
-      ? [`Unconfigured tier${unconfigured.length === 1 ? '' : 's'}: ${unconfigured.join(', ')}. Run 'construct models --apply' or set CX_MODEL_<TIER>.`]
-      : [],
-    resolution: resolved,
-  };
-}
-
-export function formatModelStatus(options = {}) {
-  const resolved = resolveModelTiers(options);
-
-  let output = 'Model Configuration:\n\n';
-
-  for (const tier of ['reasoning', 'standard', 'fast']) {
-    const model = resolved.models[tier];
-    const source = resolved.sources[tier];
-    const icon = source === 'not configured' ? '⚠' : '✓';
-    const display = model ?? '(not configured)';
-
-    output += `${icon} ${tier.padEnd(10)} ${display}\n`;
-    output += `  Source: ${source}\n\n`;
-  }
-
-  const unconfigured = Object.entries(resolved.sources)
-    .filter(([, source]) => source === 'not configured')
-    .map(([tier]) => tier);
-  if (unconfigured.length > 0) {
-    output += `\nUnconfigured: ${unconfigured.join(', ')}. To configure:\n`;
-    output += '  construct models --apply        (interactive, picks from available providers)\n';
-    output += '  export CX_MODEL_REASONING=...   (env override)\n';
-    output += '  export CX_MODEL_STANDARD=...\n';
-    output += '  export CX_MODEL_FAST=...\n';
-  }
-
-  return output;
-}
-
-// ---------------------------------------------------------------------------
-// Backwards compatibility
-// ---------------------------------------------------------------------------
-
-/**
- * Legacy wrapper for code that expects the old interface.
- * New code should use resolveModelTiers() directly.
- */
-export function readCurrentModels(envPath, registryModels = {}) {
-  // Maintains backwards compatibility with existing code
-  // while using the new resolution logic internally
-  
-  const env = {};
-  
-  // Load from env file if provided
-  if (envPath && fs.existsSync(envPath)) {
-    const content = fs.readFileSync(envPath, 'utf8');
-    for (const line of content.split('\n')) {
-      const match = line.match(/^([^=]+)=(.*)$/);
-      if (match) {
-        env[match[1].trim()] = match[2].trim();
-      }
-    }
-  }
-  
-  // Merge with process.env
-  Object.assign(env, process.env);
-  
-  const resolved = resolveModelTiers({ env });
-  
-  // Return in legacy format
-  return {
-    reasoning: resolved.models.reasoning,
-    standard: resolved.models.standard,
-    fast: resolved.models.fast,
-    // Legacy code expects these fields
-    _resolved: resolved,
-  };
-}
-
-export function setTierModel(tier, model, envPath) {
-  // Simplified interface for setting a model
-  // In practice, this should update the user config file
-  
-  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
-    throw new Error(`Invalid tier: ${tier}. Must be reasoning, standard, or fast.`);
-  }
-  
-  const envKey = `${ENV_PREFIX}_${tier.toUpperCase()}`;
-  
-  return {
-    success: true,
-    tier,
-    model,
-    envKey,
-    instruction: `Add to your shell profile: export ${envKey}="${model}"`,
-  };
-}
+export {
+  resolveModelTiers,
+  getModelForTier,
+  getModelSource,
+  validateModelTiers,
+  formatModelStatus,
+  readCurrentModels,
+  setTierModel,
+} from './model-router.mjs';