@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/mcp/server.mjs

@@ -13,7 +13,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
-import { loadConstructEnv } from '../env-config.mjs';
+import { loadConstructEnv, prepareConstructEnv } from '../runtime-env.mjs';
 import { getInstalledVersion } from '../version.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
@@ -21,7 +21,7 @@ import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } fr
 // Apply config.env values to process.env, letting config.env win over shell env
 // so telemetry/OpenRouter credentials are always correct regardless of host env.
 {
-  const confEnv = loadConstructEnv({ warn: false });
+  const confEnv = prepareConstructEnv({ warn: false });
   for (const [k, v] of Object.entries(confEnv)) {
     process.env[k] = v;
   }
@@ -58,7 +58,7 @@ import {
   profileCreate, profileArchive, sandboxList, learningStatus,
   knowledgeGraphAsk,
 } from './tools/profile.mjs';
-import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve } from './tools/embedded-contract.mjs';
+import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve, artifactWorkflow } from './tools/embedded-contract.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -170,7 +170,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'extract_document_text',
-      description: 'Extracts readable text from a local document path. High-fidelity backend (docling Python sidecar via uv, whisper.cpp for audio/video) is wired into `construct ingest`; this MCP path returns the legacy regex extraction for backwards compatibility. Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
+      description: 'Extracts readable text from a local document path. Uses node-native extractors (unpdf/mammoth) first; escalates to the docling Python sidecar or whisper.cpp when needed (same pipeline as `construct ingest`). Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -375,7 +375,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'get_skill',
-      description: 'Reads a specific skill playbook from the Construct knowledge base (e.g. "security/security-arch", "web/design-quality").',
+      description: 'Reads a specific skill playbook from the Construct knowledge base (e.g. "docs/adr-workflow", "roles/engineer", "architecture/security-arch").',
       inputSchema: {
         type: 'object',
         properties: {
@@ -932,15 +932,50 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'document_export',
-      description: 'Convert a markdown file into a distributable PDF, DOCX, or HTML document via Pandoc (DOCX/HTML) and Typst (PDF engine), per ADR-0024. Both engines are optional system binaries discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
+      description: 'Convert a markdown file into a distributable document — PDF, DOCX, legacy DOC (LibreOffice), deck HTML, PPTX, HTML, RTF, ODT, EPUB, LaTeX, plain text, or Markdown — via Pandoc and Typst (PDF engine) plus optional pptxgenjs/LibreOffice, per ADR-0024. Engines are optional dependencies discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
       inputSchema: {
         type: 'object',
         required: ['format'],
         properties: {
           input_path: { type: 'string', description: 'Absolute path to the markdown source file (required unless detect_only=true).' },
           output_path: { type: 'string', description: 'Optional absolute output path; defaults to <input>.<format> next to the source.' },
-          format: { type: 'string', enum: ['pdf', 'docx', 'html'], description: 'Target format.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Target format.' },
           detect_only: { type: 'boolean', description: 'When true, report binary availability without exporting. Default false.' },
+          figures: { type: 'boolean', description: 'When true, render d2/mermaid via pandoc-ext/diagram filter. Default false.' },
+        },
+      },
+    },
+    {
+      name: 'publish_detect',
+      description: 'Detect availability of publish pipeline tooling: Pandoc/Typst export, pandoc-ext/diagram figures, VHS terminal demos, and Playwright dashboard demos.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Export format to probe (default pdf).' },
+          figures: { type: 'boolean', description: 'Include figure binaries (default true).' },
+          demo: { type: 'string', description: 'When set, require VHS/asciinema for terminal demo.' },
+          dashboard_demo: { type: 'string', description: 'When set, require Playwright workspace for dashboard demo.' },
+        },
+      },
+    },
+    {
+      name: 'publish_run',
+      description: 'Run the publish pipeline: export markdown with optional figure filter and optional demo recordings. Use dry_run=true to probe tooling only.',
+      inputSchema: {
+        type: 'object',
+        required: ['input_path'],
+        properties: {
+          input_path: { type: 'string', description: 'Absolute path to markdown research brief.' },
+          output_path: { type: 'string', description: 'Optional output path for export.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'], description: 'Target format (default pdf).' },
+          demo: { type: 'string', description: 'Terminal tape name to record.' },
+          dashboard_demo: { type: 'string', description: 'Dashboard Playwright demo spec basename.' },
+          figures: { type: 'boolean', description: 'Render diagrams (default true).' },
+          strict: { type: 'boolean', description: 'Fail when toolchain or release gate fails (default true).' },
+          source_only: { type: 'boolean', description: 'Write sources only (default false).' },
+          no_gate: { type: 'boolean', description: 'Skip artifact release gate (default false).' },
+          artifact_type: { type: 'string', description: 'Manifest doc type for release gate when path inference is ambiguous.' },
+          dry_run: { type: 'boolean', description: 'Detect tooling only (default false).' },
         },
       },
     },
@@ -1099,6 +1134,23 @@ const ALL_TOOL_DEFS = [
         },
       },
     },
+    {
+      name: 'artifact_workflow',
+      description: 'Plan a manifest-backed document artifact workflow and return a truthful provenance report. It separates planned steps from locally executed validation/export and never claims a host-planned specialist review or rewrite was completed. Durable local export requires approval_mode=allow-durable-write.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          input: { type: 'string', description: 'Natural-language artifact request.' },
+          artifact_type: { type: 'string', description: 'Registered manifest document class.' },
+          file_path: { type: 'string', description: 'Optional existing source document for local validation/export.' },
+          format: { type: 'string', description: 'Distribution format such as pdf, docx, html, deck, or pptx.' },
+          output_path: { type: 'string', description: 'Optional output destination when locally exporting.' },
+          branding: { type: 'string', enum: ['construct', 'plain'], description: 'Construct is default; plain is an explicit opt-out.' },
+          overrides: { type: 'object', description: 'Per-invocation manifest workflow overrides.' },
+          approval_mode: { type: 'string', enum: ['proposal-only', 'requires-human-approval', 'allow-durable-write'], description: 'Only allow-durable-write performs local validation/export.' },
+        },
+      },
+    },
     {
       name: 'model_resolve',
       description: 'Resolve which model an embedded Construct workflow should use given the host/IDE provider context. Precedence: host model → same-provider-family fallback → Construct tier default → structured config error. Never reads or returns credential values (requiresCredential is a boolean) and never claims unverified provider health. Read-only; performs no writes.',
@@ -1270,7 +1322,7 @@ export async function dispatchToolByName(name, args = {}) {
     if (name === 'agent_health') result = agentHealth(args);
     else if (name === 'summarize_diff') result = summarizeDiff(args);
     else if (name === 'scan_file') result = scanFile(args);
-    else if (name === 'extract_document_text') result = extractDocumentText(args);
+    else if (name === 'extract_document_text') result = await extractDocumentText(args);
     else if (name === 'ingest_document') result = await ingestDocument(args);
     else if (name === 'infer_document_schema') result = await inferDocumentSchemaTool(args);
     else if (name === 'list_schema_artifacts') result = listSchemaArtifactsTool(args);
@@ -1324,9 +1376,49 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'document_export') {
       const { detect, exportMarkdown } = await import('../document-export.mjs');
       if (args.detect_only) {
-        result = detect(args.format);
+        result = detect(args.format, process.env, { figures: Boolean(args.figures) });
+      } else {
+        result = exportMarkdown({
+          inputPath: args.input_path,
+          outputPath: args.output_path,
+          format: args.format,
+          figures: Boolean(args.figures),
+        });
+      }
+    }
+    else if (name === 'publish_detect') {
+      const { detectPublishPipeline } = await import('../publish-tooling.mjs');
+      result = detectPublishPipeline({
+        format: args.format || 'pdf',
+        includeFigures: args.figures !== false,
+        includeTerminalDemo: Boolean(args.demo),
+        includeDashboardDemo: Boolean(args.dashboard_demo),
+      });
+    }
+    else if (name === 'publish_run') {
+      const { runPublish } = await import('../publish.mjs');
+      if (args.dry_run) {
+        const { detectPublishPipeline } = await import('../publish-tooling.mjs');
+        result = detectPublishPipeline({
+          format: args.format || 'pdf',
+          includeFigures: args.figures !== false,
+          includeTerminalDemo: Boolean(args.demo),
+          includeDashboardDemo: Boolean(args.dashboard_demo),
+        });
       } else {
-        result = exportMarkdown({ inputPath: args.input_path, outputPath: args.output_path, format: args.format });
+        result = runPublish({
+          inputPath: args.input_path,
+          format: args.format || 'pdf',
+          outputPath: args.output_path,
+          demos: args.demo ? [args.demo] : [],
+          dashboardDemos: args.dashboard_demo ? [args.dashboard_demo] : [],
+          figures: args.figures !== false,
+          strict: args.strict !== false,
+          gate: args.no_gate !== true,
+          artifactType: args.artifact_type || args.type || null,
+          sourceOnly: Boolean(args.source_only),
+          repoRoot: process.cwd(),
+        });
       }
     }
     else if (name === 'profile_show') result = profileShow(args);
@@ -1346,6 +1438,7 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'workflow_invoke') result = await workflowInvoke(args);
     else if (name === 'capability_describe') result = capabilityDescribe(args);
     else if (name === 'construct_execution_resolve') result = executionResolve(args);
+    else if (name === 'artifact_workflow') result = artifactWorkflow(args);
     else if (name === 'orchestration_run') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationRun(args); }
     else if (name === 'orchestration_status') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationStatus(args); }
     else if (name === 'construct_call') {

package/lib/mcp/stdio-mcp-probe.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/mcp/stdio-mcp-probe.mjs — newline-delimited JSON-RPC probe for stdio MCP servers.
+ *
+ * Spawns a child MCP process, completes initialize + notifications/initialized, then
+ * issues tools/list to capture serialized tool schemas for token-budget fixtures.
+ * Stdout is the only protocol channel; stderr is ignored.
+ */
+
+import { spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 25_000;
+
+function parseFrames(chunk, state) {
+  state.buffer += chunk;
+  let idx;
+  while ((idx = state.buffer.indexOf('\n')) >= 0) {
+    const raw = state.buffer.slice(0, idx).trim();
+    state.buffer = state.buffer.slice(idx + 1);
+    if (!raw) continue;
+    try {
+      state.frames.push(JSON.parse(raw));
+    } catch {
+      /* non-JSON noise */
+    }
+  }
+}
+
+function send(child, frame) {
+  child.stdin.write(`${JSON.stringify(frame)}\n`);
+}
+
+function waitForFrame(frames, predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = () => {
+      const hit = frames.find(predicate);
+      if (hit) {
+        resolve(hit);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        reject(new Error(`Timed out after ${timeoutMs}ms; frames=${frames.length}`));
+        return;
+      }
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+// Probe a stdio MCP server and return the tools/list result array.
+
+export async function probeStdioMcpTools(command, args, {
+  env = {},
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const child = spawn(command, args, {
+    env: { ...process.env, ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const state = { buffer: '', frames: [] };
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => parseFrames(chunk, state));
+
+  const cleanup = () => {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      /* already exited */
+    }
+  };
+
+  try {
+    send(child, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'construct-mcp-probe', version: '1' },
+      },
+    });
+    await waitForFrame(state.frames, (f) => f.id === 1, timeoutMs);
+    send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
+    send(child, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const listFrame = await waitForFrame(state.frames, (f) => f.id === 2, timeoutMs);
+    if (listFrame.error) {
+      throw new Error(listFrame.error.message || JSON.stringify(listFrame.error));
+    }
+    return listFrame.result?.tools || [];
+  } finally {
+    cleanup();
+  }
+}
+
+// Parse JSON or MCP-over-SSE (event: message / data: {...}) bodies from HTTP MCP hosts.
+
+function parseMcpHttpFrame(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('data:')) continue;
+      const payload = trimmed.slice(5).trim();
+      if (!payload) continue;
+      try {
+        return JSON.parse(payload);
+      } catch {
+        /* try next data line */
+      }
+    }
+    throw new Error('response was not JSON or SSE data');
+  }
+}
+
+// Probe an HTTP MCP endpoint (GitHub Copilot MCP) with bearer auth.
+
+export async function probeHttpMcpTools(url, headers = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const initBody = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'construct-mcp-probe', version: '1' },
+    },
+  };
+  const listBody = { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} };
+  const commonHeaders = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    ...headers,
+  };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  async function postRpc(body, extraHeaders = {}) {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { ...commonHeaders, ...extraHeaders },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    return { res, text };
+  }
+
+  try {
+    const { res: initRes, text: initText } = await postRpc(initBody);
+    if (!initRes.ok) {
+      throw new Error(`initialize HTTP ${initRes.status}: ${initText.slice(0, 160)}`);
+    }
+    parseMcpHttpFrame(initText);
+
+    const sessionId = initRes.headers.get('mcp-session-id')
+      || initRes.headers.get('Mcp-Session-Id')
+      || null;
+    const sessionHeaders = sessionId ? { 'mcp-session-id': sessionId } : {};
+
+    const { res: listRes, text: listText } = await postRpc(listBody, sessionHeaders);
+    if (!listRes.ok) {
+      throw new Error(`tools/list HTTP ${listRes.status}: ${listText.slice(0, 160)}`);
+    }
+    const frame = parseMcpHttpFrame(listText);
+    if (frame.error) {
+      throw new Error(frame.error.message || JSON.stringify(frame.error));
+    }
+    return frame.result?.tools || [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Probe the Construct memory stdio bridge, which forwards tools/list to cm.
+
+export async function probeMemoryBridgeTools({
+  bridgePath,
+  backendUrl = 'http://127.0.0.1:8765/',
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  return probeStdioMcpTools(process.execPath, [bridgePath], {
+    env: { CONSTRUCT_MEMORY_BRIDGE_URL: backendUrl },
+    timeoutMs,
+  });
+}

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/embedded-contract.mjs

@@ -14,6 +14,7 @@ import { invokeWorkflow as invokeWorkflowCore } from '../../embedded-contract/wo
 import { buildCapabilityContract } from '../../embedded-contract/capability.mjs';
 import { resolveExecution as resolveExecutionCore } from '../../embedded-contract/execution.mjs';
 import { resolveInput } from '../../embedded-contract/ingest.mjs';
+import { runArtifactWorkflow as runArtifactWorkflowCore } from '../../artifact-workflow.mjs';
 
 async function ingestArgs(args) {
   if (args.input || !args.file_path) return { input: args.input, ingestion: undefined };
@@ -91,3 +92,16 @@ export function executionResolve(args = {}) {
   };
   return wrapContractResult(resolveExecutionCore(request), { surface: 'mcp' });
 }
+
+export function artifactWorkflow(args = {}) {
+  return wrapContractResult(runArtifactWorkflowCore({
+    input: args.input || args.request,
+    artifactType: args.artifact_type,
+    filePath: args.file_path,
+    format: args.format,
+    outputPath: args.output_path,
+    branding: args.branding,
+    overrides: args.overrides,
+    approvalMode: args.approval_mode,
+  }), { surface: 'mcp' });
+}

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`.