@geraldmaron/construct 1.0.19 → 1.0.20

package/lib/embedded-contract/ingest.mjs

@@ -10,13 +10,18 @@
  * error or a clearly-flagged best-effort fallback — never silent gibberish.
  *
  * Surfaces (CLI/MCP/SDK) own I/O and call this; the contract cores stay pure and
- * receive the resolved text plus an `ingestion` metadata block to echo back.
+ * receive the resolved text plus an `ingestion` metadata block to echo back. The
+ * `ingestion` block records the resolved strategy (adapter | provider) and the
+ * provider/model when one was selected, so the extraction choice is never opaque.
  */
 
 import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 
 import { extractDocumentTextAsync, isExtractableDocumentPath } from '../document-extract.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveIngestStrategy } from '../ingest/strategy.mjs';
+import { extractViaProvider } from '../ingest/provider-extract.mjs';
 
 /**
  * Resolve contract input from inline text or a file path.
@@ -25,9 +30,14 @@ import { extractDocumentTextAsync, isExtractableDocumentPath } from '../document
  * @param {string} [opts.input]     Inline text (returned as-is when provided).
  * @param {string} [opts.filePath]  Path to extract when no inline text is given.
  * @param {number} [opts.maxChars]
+ * @param {object} [opts.config]    Loaded project config (for strategy resolution).
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.strategy]  Explicit strategy override.
+ * @param {string} [opts.cwd]       Working directory for locating project config.
+ * @param {Function} [opts.fetchImpl] Injectable fetch for provider extraction (tests).
  * @returns {Promise<{text:string, ingestion:(object|null), error:(object|null)}>}
  */
-export async function resolveInput({ input = '', filePath = '', maxChars = null } = {}) {
+export async function resolveInput({ input = '', filePath = '', maxChars = null, config = null, env = process.env, strategy = null, cwd = process.cwd(), fetchImpl = undefined } = {}) {
   if (input && input.trim()) {
     return { text: input, ingestion: null, error: null };
   }
@@ -35,6 +45,48 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
     return { text: '', ingestion: null, error: null };
   }
 
+  const projectConfig = config || loadProjectConfig(cwd, env).config;
+  const resolved = resolveIngestStrategy({ config: projectConfig, env, override: strategy });
+  const strategyMeta = { strategy: resolved.strategy, fallback: resolved.fallback, model: resolved.model, provider: resolved.provider };
+
+  // Provider strategy runs a concrete provider-backed extraction. On failure
+  // the fallback policy decides: `adapter` routes to the local extractor and
+  // records the fallback; any other policy surfaces the structured provider
+  // error rather than silently masking the strategy mismatch.
+
+  let providerFallback = null;
+  if (resolved.strategy === 'provider') {
+    try {
+      const extracted = await extractViaProvider({ filePath, model: resolved.model, provider: resolved.provider, maxChars, env, ...(fetchImpl ? { fetchImpl } : {}) });
+      return {
+        text: extracted.text || '',
+        ingestion: {
+          sourcePath: filePath,
+          extractionMethod: extracted.extractionMethod,
+          characters: extracted.characters,
+          truncated: extracted.truncated,
+          droppedInfo: extracted.droppedInfo || [],
+          ...strategyMeta,
+          fallbackApplied: null,
+        },
+        error: null,
+      };
+    } catch (providerErr) {
+      if (resolved.fallback !== 'adapter') {
+        return {
+          text: '',
+          ingestion: { sourcePath: filePath, extractionMethod: 'provider-failed', droppedInfo: [], ...strategyMeta },
+          error: {
+            code: providerErr.code || 'PROVIDER_EXTRACTION_FAILED',
+            reason: providerErr.message,
+            remediation: providerErr.remediation || 'Set ingest.fallback to "adapter" to use the local extractor, or select the adapter strategy.',
+          },
+        };
+      }
+      providerFallback = { from: 'provider', to: 'adapter', reason: providerErr.message, code: providerErr.code || 'PROVIDER_EXTRACTION_FAILED' };
+    }
+  }
+
   if (isExtractableDocumentPath(filePath)) {
     try {
       const extracted = await extractDocumentTextAsync(filePath, { maxChars });
@@ -46,17 +98,19 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
           characters: extracted.characters,
           truncated: extracted.truncated,
           droppedInfo: extracted.droppedInfo || [],
+          ...strategyMeta,
+          fallbackApplied: providerFallback,
         },
         error: null,
       };
     } catch (err) {
       if (err && err.code === 'ASR_REQUIRED') {
-        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) or transcribe the file before sending.' } };
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [], ...strategyMeta }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) or transcribe the file before sending.' } };
       }
       if (err && /WHISPER_BINARY_MISSING/.test(String(err.message))) {
-        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) to transcribe audio/video.' } };
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [], ...strategyMeta }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) to transcribe audio/video.' } };
       }
-      return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'EXTRACTION_FAILED', reason: err.message, remediation: 'Verify the file is readable and of a supported type.' } };
+      return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [], ...strategyMeta }, error: { code: 'EXTRACTION_FAILED', reason: err.message, remediation: 'Verify the file is readable and of a supported type.' } };
     }
   }
 
@@ -68,10 +122,10 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
     const text = readFileSync(filePath, 'utf8');
     return {
       text,
-      ingestion: { sourcePath: filePath, extractionMethod: 'raw-utf8', droppedInfo: [], note: `No structured extractor for ${extname(filePath) || 'this type'}; read as plain text.` },
+      ingestion: { sourcePath: filePath, extractionMethod: 'raw-utf8', droppedInfo: [], note: `No structured extractor for ${extname(filePath) || 'this type'}; read as plain text.`, ...strategyMeta, fallbackApplied: providerFallback },
       error: null,
     };
   } catch (err) {
-    return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'FILE_UNREADABLE', reason: err.message, remediation: 'Check the path and permissions.' } };
+    return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [], ...strategyMeta }, error: { code: 'FILE_UNREADABLE', reason: err.message, remediation: 'Check the path and permissions.' } };
   }
 }

package/lib/hooks/_lib/output-mode.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/hooks/_lib/output-mode.mjs — capability-aware SessionStart output routing.
+ *
+ * A SessionStart hook's stdout is injected into the model's context. In a
+ * non-interactive / SDK / `claude -p` one-shot, that verbose context pollutes a
+ * caller's machine-oriented stdout and can spill startup payloads into editors
+ * and logs. This resolver picks the channel the payload should use so stdout
+ * stays reserved for the caller's output contract while diagnostics remain
+ * recoverable.
+ *
+ * Modes (`CONSTRUCT_HOOK_OUTPUT_MODE` env or `hooks.outputMode` config, env >
+ * config > default): `stdout` injects as context (interactive default),
+ * `stderr` writes to stderr, `silent` writes only to a debug log, and `auto`
+ * resolves to stdout when interactive and silent when not.
+ *
+ * Honest limitation: Claude Code exposes no reliable in-hook signal for
+ * interactive vs print/SDK mode (`CLAUDECODE=1` is set in both; `isTTY` is false
+ * even interactively because hooks run without a controlling terminal). So
+ * `auto` detects non-interactive only from signals that ARE reliable — `CI`,
+ * `NODE_ENV=test`, and an explicit `CONSTRUCT_NONINTERACTIVE` flag — and SDK /
+ * host adapters set `CONSTRUCT_HOOK_OUTPUT_MODE` explicitly. `auto` never
+ * suppresses on an ambiguous signal, so real interactive sessions keep their
+ * rich startup context.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+import { resolveSetting, loadProjectConfig } from '../../config/project-config.mjs';
+import { HOOK_OUTPUT_MODES } from '../../config/schema.mjs';
+
+export { HOOK_OUTPUT_MODES };
+
+function truthyFlag(value) {
+  if (value === undefined || value === null) return false;
+  const v = String(value).trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+}
+
+/**
+ * Whether the invocation is non-interactive, using only reliable signals.
+ * @param {Record<string,string>} [env]
+ * @returns {boolean}
+ */
+export function isNonInteractive(env = process.env) {
+  if (env.CI === 'true') return true;
+  if (env.NODE_ENV === 'test') return true;
+  if (truthyFlag(env.CONSTRUCT_NONINTERACTIVE)) return true;
+  return false;
+}
+
+function normalizeMode(value) {
+  const m = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return HOOK_OUTPUT_MODES.includes(m) ? m : null;
+}
+
+/**
+ * Resolve the concrete output channel for the SessionStart payload.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {Record<string,string>} [opts.env]
+ * @param {object} [opts.config]   loaded project config; read from cwd when omitted
+ * @returns {{mode:('stdout'|'stderr'|'silent'), requested:string, source:string, nonInteractive:boolean}}
+ */
+export function resolveHookOutputMode({ cwd = process.cwd(), env = process.env, config } = {}) {
+  let cfg = config;
+  if (cfg === undefined) {
+    try { cfg = loadProjectConfig(cwd, env).config; } catch { cfg = null; }
+  }
+  const setting = resolveSetting({ config: cfg, jsonPath: 'hooks.outputMode', env, envKey: 'CONSTRUCT_HOOK_OUTPUT_MODE', defaultValue: 'auto' });
+  const requested = normalizeMode(setting.value) || 'auto';
+  const nonInteractive = isNonInteractive(env);
+  const mode = requested !== 'auto' ? requested : (nonInteractive ? 'silent' : 'stdout');
+  return { mode, requested, source: setting.source, nonInteractive };
+}
+
+/**
+ * Route the SessionStart payload to the resolved channel. `silent` preserves the
+ * payload in a debug log so diagnostics stay available without touching the
+ * caller's stdout/stderr. Returns the channel actually used.
+ *
+ * @param {object} opts
+ * @param {string} opts.payload
+ * @param {string} opts.mode      one of stdout|stderr|silent
+ * @param {string} [opts.homeDir]
+ * @param {{write:Function}} [opts.stdout]
+ * @param {{write:Function}} [opts.stderr]
+ * @returns {string} the channel used
+ */
+export function writeHookContext({ payload, mode, homeDir = homedir(), stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (mode === 'stdout') { stdout.write(payload); return 'stdout'; }
+  if (mode === 'stderr') { stderr.write(payload); return 'stderr'; }
+  try {
+    const dir = join(homeDir, '.cx');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'session-start-last.log'), payload);
+  } catch { /* best effort — never block the session on a debug-log write */ }
+  return 'silent';
+}

package/lib/hooks/session-start.mjs

@@ -23,6 +23,7 @@ import { createSession, lastSession, buildResumeContext } from '../session-store
 import { listObservations, searchObservations } from '../observation-store.mjs';
 import { countEntities } from '../entity-store.mjs';
 import { logHookFailure } from './_lib/log.mjs';
+import { resolveHookOutputMode, writeHookContext } from './_lib/output-mode.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = resolve(MODULE_DIR, '..', '..', 'bin', 'construct');
@@ -378,7 +379,18 @@ try {
   permissionPostureNote = buildPermissionPostureLine({ cwd });
 } catch { /* best effort */ }
 
-process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`);
+// SessionStart context is injected via stdout. In non-interactive / SDK runs
+// that pollutes the caller's output contract, so the resolved output mode routes
+// the payload to stdout (interactive), stderr, or a debug log (silent).
+
+const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
+try {
+  const { mode } = resolveHookOutputMode({ cwd, env: process.env });
+  writeHookContext({ payload, mode });
+} catch (err) {
+  logHookFailure({ hook: 'session-start', err, phase: 'emit' });
+  process.stdout.write(payload);
+}
 // Auto-bootstrap the policy-engine gate. session-start has just emitted
 // branch + recent commits + prior observations + context-state — that is
 // already grounding; mark the session bootstrapped so the PreToolUse rule

package/lib/ingest/provider-extract.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/ingest/provider-extract.mjs — concrete provider-backed document extraction.
+ *
+ * The `provider` ingest strategy routes document understanding through the
+ * configured provider/model instead of the local binary adapters. This module
+ * is that route: it reads a file, builds a provider-native request, and returns
+ * extracted text in the same shape `extractDocumentTextAsync` produces so every
+ * caller treats adapter and provider results uniformly.
+ *
+ * Capability is honest, never silently degraded. Images and PDFs are sent as
+ * multimodal blocks (Anthropic `image`/`document`, OpenRouter `image_url`);
+ * text-class files are sent inline for faithful extraction/normalization;
+ * audio/video and Office/zip documents are NOT chat-extractable and raise a
+ * specific `PROVIDER_MEDIA_UNSUPPORTED` so the strategy's fallback policy — not
+ * a hidden code path — decides whether the local adapter handles them. Provider
+ * selection follows the resolved model (Anthropic when the provider/model is
+ * Claude-family, OpenRouter otherwise); a missing key surfaces as a structured
+ * `PROVIDER_KEY_MISSING` rather than an opaque HTTP failure.
+ *
+ * `fetchImpl` and `env` are injectable so the provider path is exercised end to
+ * end against a mock provider without a live key.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+import {
+  AUDIO_VIDEO_EXTS,
+  UTF8_TEXT_EXTS,
+  TRANSCRIPT_EXTS,
+  CALENDAR_EXTS,
+} from '../document-extract.mjs';
+
+export const PROVIDER_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
+
+const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+const DEFAULT_PROMPT = 'Extract the complete textual content of this document faithfully and verbatim. Preserve headings, lists, and tables as Markdown. Do not summarize, interpret, or add commentary — output only the extracted content.';
+
+const MAX_OUTPUT_TOKENS = 4096;
+
+function providerError(code, reason, remediation) {
+  const err = new Error(reason);
+  err.code = code;
+  err.remediation = remediation;
+  return err;
+}
+
+function classifyMedia(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (PROVIDER_IMAGE_EXTS.has(ext)) return 'image';
+  if (ext === '.pdf') return 'pdf';
+  if (AUDIO_VIDEO_EXTS.has(ext)) return 'audio-video';
+  if (UTF8_TEXT_EXTS.has(ext) || TRANSCRIPT_EXTS.has(ext) || CALENDAR_EXTS.has(ext)) return 'text';
+  return 'binary-doc';
+}
+
+function isAnthropic(provider, model) {
+  return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
+}
+
+// Key resolution mirrors the daemon's cheap sources (env, then the two dotenv
+// files) without the shell-rc/1Password walk, which belongs to long-running
+// processes rather than a per-file extraction call. Ambient dotenv discovery
+// only augments the real process env; a caller that injects an explicit env
+// object (embedded callers, tests) is authoritative and hermetic.
+
+function resolveKey(varName, env, allowAmbient) {
+  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
+  if (!allowAmbient) return null;
+  for (const file of [join(homedir(), '.construct', 'config.env'), join(homedir(), '.env')]) {
+    try {
+      if (!existsSync(file)) continue;
+      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+      if (m && m[1]) return m[1].trim();
+    } catch { /* unreadable dotenv is not authoritative */ }
+  }
+  return null;
+}
+
+async function bodyExcerpt(res) {
+  try {
+    const text = await res.text();
+    return text.slice(0, 200);
+  } catch {
+    return '';
+  }
+}
+
+async function callAnthropic({ model, apiKey, content, fetchImpl }) {
+  const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: model.replace(/^anthropic\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      messages: [{ role: 'user', content }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXTRACTION_FAILED', `Anthropic extraction failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set ingest.fallback to "adapter".');
+  }
+  const data = await res.json();
+  return (data.content || []).filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+}
+
+async function callOpenRouter({ model, apiKey, content, fetchImpl }) {
+  const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/construct' },
+    body: JSON.stringify({
+      model: model.replace(/^openrouter\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      messages: [{ role: 'user', content }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXTRACTION_FAILED', `OpenRouter extraction failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set ingest.fallback to "adapter".');
+  }
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || '';
+}
+
+/**
+ * Extract a document's text through the configured provider/model.
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath
+ * @param {string} opts.model            resolved provider model id
+ * @param {string} [opts.provider]       resolved provider id (selects the API)
+ * @param {number} [opts.maxChars]       truncate returned text to this length
+ * @param {Record<string,string>} [opts.env]
+ * @param {Function} [opts.fetchImpl]    injectable fetch (for tests)
+ * @param {string} [opts.prompt]
+ * @returns {Promise<{text:string, extractionMethod:string, characters:number, truncated:boolean, droppedInfo:Array}>}
+ */
+export async function extractViaProvider({ filePath, model, provider = null, maxChars = null, env = process.env, fetchImpl = globalThis.fetch, prompt = DEFAULT_PROMPT } = {}) {
+  if (!filePath) throw providerError('PROVIDER_NO_INPUT', 'No file path supplied for provider extraction.', 'Pass a readable file path.');
+  if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider strategy selected but no provider model resolved.', 'Configure the model tier registry so the ingest tier resolves a model, or set ingest.fallback to "adapter".');
+  if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider extraction.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
+
+  const media = classifyMedia(filePath);
+  if (media === 'audio-video') {
+    throw providerError('PROVIDER_MEDIA_UNSUPPORTED', `Provider chat extraction does not transcribe audio/video (${extname(filePath)}).`, 'Use the adapter strategy (whisper ASR) for audio/video, or set ingest.fallback to "adapter".');
+  }
+  if (media === 'binary-doc') {
+    throw providerError('PROVIDER_MEDIA_UNSUPPORTED', `Provider chat extraction does not accept ${extname(filePath) || 'this type'} directly.`, 'Use the adapter strategy for Office/zip documents, or set ingest.fallback to "adapter".');
+  }
+
+  const anthropic = isAnthropic(provider, model);
+  const keyVar = anthropic ? 'ANTHROPIC_API_KEY' : 'OPENROUTER_API_KEY';
+  const apiKey = resolveKey(keyVar, env, env === process.env);
+  if (!apiKey) {
+    throw providerError('PROVIDER_KEY_MISSING', `No API key for ${anthropic ? 'Anthropic' : 'OpenRouter'} provider extraction.`, `Set ${keyVar}, or set ingest.fallback to "adapter".`);
+  }
+
+  let text;
+  if (media === 'text') {
+    const raw = readFileSync(filePath, 'utf8');
+    const promptText = `${prompt}\n\n---\n${raw}`;
+    text = anthropic
+      ? await callAnthropic({ model, apiKey, fetchImpl, content: [{ type: 'text', text: promptText }] })
+      : await callOpenRouter({ model, apiKey, fetchImpl, content: promptText });
+  } else {
+    const base64 = readFileSync(filePath).toString('base64');
+    if (anthropic) {
+      const mediaBlock = media === 'image'
+        ? { type: 'image', source: { type: 'base64', media_type: IMAGE_MIME[extname(filePath).toLowerCase()], data: base64 } }
+        : { type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: base64 } };
+      text = await callAnthropic({ model, apiKey, fetchImpl, content: [mediaBlock, { type: 'text', text: prompt }] });
+    } else if (media === 'pdf') {
+      throw providerError('PROVIDER_MEDIA_UNSUPPORTED', 'PDF provider extraction requires an Anthropic-family model in this build.', 'Select an Anthropic ingest model, or set ingest.fallback to "adapter".');
+    } else {
+      const dataUrl = `data:${IMAGE_MIME[extname(filePath).toLowerCase()]};base64,${base64}`;
+      text = await callOpenRouter({ model, apiKey, fetchImpl, content: [{ type: 'text', text: prompt }, { type: 'image_url', image_url: { url: dataUrl } }] });
+    }
+  }
+
+  text = text || '';
+  let truncated = false;
+  if (maxChars && text.length > maxChars) {
+    text = text.slice(0, maxChars);
+    truncated = true;
+  }
+
+  return {
+    text,
+    extractionMethod: `provider:${anthropic ? 'anthropic' : 'openrouter'}:${model}`,
+    characters: text.length,
+    truncated,
+    droppedInfo: [],
+  };
+}

package/lib/ingest/strategy.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/ingest/strategy.mjs — resolve the ingest extraction strategy and provider model.
+ *
+ * Construct's ingest path historically extracted documents through local binary
+ * adapters (docling/whisper/pdftotext) without surfacing that choice. This module
+ * makes the choice explicit and configurable:
+ *   - `adapter` (default): the local-extractor pipeline, byte-for-byte unchanged.
+ *   - `provider`: route document understanding through the configured provider/model.
+ * A `fallback` policy (`none`/`provider`/`adapter`) governs what happens on
+ * primary-path failure; the default `none` never silently masks a strategy
+ * mismatch. Resolution precedence matches the project-config convention:
+ * env > config > default. Provider/model identification reuses the embedded model
+ * resolution contract and the tier registry so no second selection surface exists.
+ */
+
+import { resolveSetting } from '../config/project-config.mjs';
+import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
+
+export const INGEST_STRATEGIES = ['adapter', 'provider'];
+export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
+
+export const DEFAULT_INGEST_STRATEGY = 'adapter';
+export const DEFAULT_INGEST_FALLBACK = 'none';
+
+function coerceEnum(value, allowed) {
+  if (typeof value !== 'string') return null;
+  const lowered = value.trim().toLowerCase();
+  return allowed.includes(lowered) ? lowered : null;
+}
+
+// The strategy step a document-understanding model serves under is `fast`; ingest
+// is an extraction/understanding pass, not a reasoning workflow. The embedded
+// resolution contract maps this tier to a concrete provider/model.
+
+const INGEST_WORKFLOW_TYPE = 'evidence-ingest';
+
+function resolveProviderModel({ env, registryPath }) {
+  const resolved = resolveEmbeddedModel({ workflowType: INGEST_WORKFLOW_TYPE }, { env, registryPath });
+  return {
+    model: resolved.selectedModel || null,
+    provider: resolved.selectedProvider || null,
+    resolutionSource: resolved.resolutionSource || null,
+    error: resolved.error || null,
+  };
+}
+
+/**
+ * Resolve the effective ingest strategy, fallback policy, and provider model.
+ *
+ * Precedence for both strategy and fallback is env > config > explicit override
+ * > default, where an explicit `override` (a CLI flag) wins over env/config when
+ * provided. The returned `model`/`provider` are non-null only when the resolved
+ * strategy is `provider` or when `fallback` could route to a provider.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]      loaded project config object
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.override]    explicit strategy override (CLI flag)
+ * @param {string} [opts.registryPath]
+ * @returns {{strategy:string, fallback:string, model:(string|null), provider:(string|null), modelResolution:(object|null)}}
+ */
+export function resolveIngestStrategy({ config = null, env = process.env, override = null, registryPath = null } = {}) {
+  const overrideStrategy = coerceEnum(override, INGEST_STRATEGIES);
+
+  const fromSettings = resolveSetting({
+    config,
+    jsonPath: 'ingest.strategy',
+    env,
+    envKey: 'CONSTRUCT_INGEST_STRATEGY',
+    defaultValue: DEFAULT_INGEST_STRATEGY,
+  });
+  const strategy = overrideStrategy
+    || coerceEnum(fromSettings.value, INGEST_STRATEGIES)
+    || DEFAULT_INGEST_STRATEGY;
+
+  const fallbackSetting = resolveSetting({
+    config,
+    jsonPath: 'ingest.fallback',
+    env,
+    envKey: 'CONSTRUCT_INGEST_FALLBACK',
+    defaultValue: DEFAULT_INGEST_FALLBACK,
+  });
+  const fallback = coerceEnum(fallbackSetting.value, INGEST_FALLBACKS) || DEFAULT_INGEST_FALLBACK;
+
+  const needsProviderModel = strategy === 'provider' || fallback === 'provider';
+  const modelResolution = needsProviderModel ? resolveProviderModel({ env, registryPath }) : null;
+
+  return {
+    strategy,
+    fallback,
+    model: modelResolution?.model || null,
+    provider: modelResolution?.provider || null,
+    modelResolution,
+  };
+}

package/lib/mcp/server.mjs

@@ -8,12 +8,14 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 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 { getInstalledVersion } from '../version.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
 import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
 
 // Apply config.env values to process.env, letting config.env win over shell env
@@ -56,7 +58,7 @@ import {
   profileCreate, profileArchive, sandboxList, learningStatus,
   knowledgeGraphAsk,
 } from './tools/profile.mjs';
-import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe } from './tools/embedded-contract.mjs';
+import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve } 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);
@@ -64,11 +66,58 @@ loadToolkitEnv(ROOT_DIR);
 
 const opts = { ROOT_DIR };
 
+// Identity an MCP host can render meaningfully: the real installed version (not a
+// hardcoded stub), a one-line description of what the server offers (shown in the
+// host's server-detail view), and a `construct://status` resource for live state.
+// Without these the host shows only "<name> · OK" with an empty detail panel.
+
+const VERSION = getInstalledVersion()?.version || 'unknown';
+const DEPLOYMENT_MODE = getDeploymentMode(process.env, { cwd: ROOT_DIR });
+const INSTRUCTIONS = [
+  `Construct MCP — agent orchestration for this workspace (v${VERSION}, ${DEPLOYMENT_MODE} mode).`,
+  'Tools cover: project context and diff review, skills/templates/teams, document ingestion and vector storage,',
+  'workflow orchestration and contracts, telemetry and scoring, and cross-session memory.',
+  'Read the `construct://status` resource for live state, or run `construct status` for full project health.',
+  'Start the dashboard with `construct dev`.',
+].join(' ');
+
 const server = new Server(
-  { name: 'construct-mcp', version: '1.0.0' },
-  { capabilities: { tools: {} } }
+  { name: 'construct-mcp', version: VERSION },
+  { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS },
 );
 
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'construct://status',
+      name: 'Construct status',
+      description: 'Live toolkit status: version, deployment mode, MCP broker, and how to get full project health.',
+      mimeType: 'application/json',
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params?.uri !== 'construct://status') {
+    throw new Error(`Unknown resource: ${req.params?.uri}`);
+  }
+  const payload = {
+    name: 'Construct',
+    version: VERSION,
+    deploymentMode: DEPLOYMENT_MODE,
+    mcpBroker: process.env.CONSTRUCT_MCP_BROKER === 'on' ? 'on' : 'off',
+    capabilities: [
+      'project-context', 'skills', 'templates', 'teams', 'document-ingestion',
+      'vector-storage', 'workflow', 'telemetry', 'memory',
+    ],
+    fullHealth: 'run `construct status`',
+    dashboard: 'run `construct dev`, then open the printed URL',
+  };
+  return {
+    contents: [{ uri: req.params.uri, mimeType: 'application/json', text: JSON.stringify(payload, null, 2) }],
+  };
+});
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
@@ -1109,6 +1158,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'construct_execution_resolve',
+      description: 'Resolve the execution-capability contract for an embedded workflow BEFORE/at workflow start: returns executionMode (construct-orchestrated | construct-prompt-only | host-direct | same-family-fallback), constructCapabilitiesActive (subset of personas/skills/workflow-routing/prompt-envelope), degraded + machine-readable degradationReason, requestedStrategy vs effectiveStrategy, and the resolved provider/model. Descriptive, not enforced: reports what Construct planned and can resolve a model for, never an observation that the host ran personas (see the semantics field). Read-only and secret-free.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          workflow_type: { type: 'string', description: 'Workflow whose orchestration plan is weighed (e.g. evidence-ingest, architecture-review). Absent ⇒ generic orchestration availability.' },
+          requested_strategy: { type: 'string', enum: ['orchestrated', 'prompt-only', 'auto'], description: 'Desired execution strategy (default auto).' },
+          use_construct: { type: 'boolean', description: 'false ⇒ host-direct (host runs without Construct capabilities). Default true.' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host is currently using, for model resolution.' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, when no host_model is given.' },
+          requested_tier: { type: 'string', enum: ['reasoning', 'standard', 'fast'], description: 'Desired model tier; overrides the workflow-type hint.' },
+          capabilities: { type: 'array', items: { type: 'string' }, description: 'Optional required capabilities; unverifiable ones are returned as warnings.' },
+          allow_cross_provider_fallback: { type: 'boolean', description: 'Permit model fallback outside the host provider family (default false).' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1190,6 +1257,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'triage_recommend') result = await triageRecommend(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 result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };