@geraldmaron/construct 1.0.19 → 1.0.21

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

@@ -16,6 +16,7 @@ import { classifyRdIntake } from '../intake/classify.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { workflowTypeForIntake } from './workflow-defs.mjs';
+import { resolveExecution } from './execution.mjs';
 
 const CONFIDENCE_FLOOR = 0.6;
 
@@ -46,7 +47,7 @@ function buildRiskFactors(triage) {
  * @returns {object}
  */
 export function recommendPlan(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
-  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null } = request;
+  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null, host, hostModel, hostProvider, constructStrategy = 'auto' } = request;
   const warnings = [];
 
   // Surface extraction provenance and flag low-yield/truncated inputs so a
@@ -109,6 +110,26 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
   if (canExecute) nextStepOptions.push({ action: 'invoke-workflow', description: 'Invoke the recommended role chain as an embedded workflow.' });
   if (!canExecute) nextStepOptions.push({ action: 'clarify', description: 'Request more detail; classification confidence is low or unknown.' });
 
+  const suggestedWorkflowType = workflowTypeForIntake(triage.intakeType);
+
+  // Execution preview: forecast the executionMode an invocation of the suggested
+  // workflow would resolve to, but only when the host supplies context — absent
+  // it, forcing a model resolution on every triage call would be wasteful and
+  // the preview would be uninformative. null keeps the field parity-stable.
+  let execution = null;
+  if (suggestedWorkflowType && (hostModel || hostProvider || (constructStrategy && constructStrategy !== 'auto'))) {
+    const e = resolveExecution({ workflowType: suggestedWorkflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider }, { env, cwd });
+    execution = {
+      executionMode: e.executionMode,
+      effectiveStrategy: e.effectiveStrategy,
+      requestedStrategy: e.requestedStrategy,
+      constructCapabilitiesActive: e.constructCapabilitiesActive,
+      degraded: e.degraded,
+      degradationReason: e.degradationReason,
+      semantics: e.semantics,
+    };
+  }
+
   return {
     classification: { intakeType: triage.intakeType, rdStage: triage.rdStage },
     ingestion,
@@ -117,7 +138,8 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
     primaryOwner,
     recommendedAction: triage.recommendedAction,
     recommendedChain: chain,
-    suggestedWorkflowType: workflowTypeForIntake(triage.intakeType),
+    suggestedWorkflowType,
+    execution,
     roleRationale: rationale,
     suggestedSkills,
     evidenceRequirements,

package/lib/embedded-contract/workflow-invoke.mjs

@@ -26,6 +26,7 @@ import { recordApprovalRequest } from '../roles/approval-surface.mjs';
 import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { resolveExecution } from './execution.mjs';
 import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs';
 
 const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
@@ -91,6 +92,7 @@ function errorResult({ workflowId, traceId, approvalMode, code, message, warning
  * @param {string} [request.host]
  * @param {string} [request.hostModel]
  * @param {string} [request.hostProvider]
+ * @param {string} [request.constructStrategy]  orchestrated | prompt-only | auto (execution mode)
  * @param {object} [opts]   { env, cwd }
  * @returns {Promise<object>}
  */
@@ -98,6 +100,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const {
     workflowType, context = {}, roleStrategy = 'auto', requestedRoles,
     approvalMode, trace = true, host, hostModel, hostProvider, ingestion = null,
+    constructStrategy = 'auto',
   } = request;
   const warnings = [];
   if (ingestion) {
@@ -129,6 +132,23 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   );
   for (const w of modelWarnings) warnings.push(`model-resolution: ${w}`);
 
+  // The execution-capability contract reports the PLANNED executionMode for this
+  // run (descriptive, not enforced — ADR-0019). Construct returns a plan; the
+  // host runtime executes it, so this never claims observed specialist execution.
+  const executionData = resolveExecution(
+    { workflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider, requestedTier: def.tier },
+    { env, cwd },
+  );
+  const execution = {
+    executionMode: executionData.executionMode,
+    effectiveStrategy: executionData.effectiveStrategy,
+    requestedStrategy: executionData.requestedStrategy,
+    constructCapabilitiesActive: executionData.constructCapabilitiesActive,
+    degraded: executionData.degraded,
+    degradationReason: executionData.degradationReason,
+    semantics: executionData.semantics,
+  };
+
   const primaryOwner = selectedRoles[0];
   const facts = contractFacts(primaryOwner);
   const skillsApplied = skillsForChain(selectedRoles, map);
@@ -204,6 +224,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     roleRationale: rationale,
     skillsApplied,
     modelResolution,
+    execution,
     outputs,
     recommendations,
     evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },

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: [],
+  };
+}