@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/embed/providers/registry.mjs

@@ -2,7 +2,9 @@
  * lib/embed/providers/registry.mjs — ProviderRegistry.
  *
  * Holds named provider instances and exposes an async factory that builds
- * the standard set from environment variables. Each provider implements:
+ * the standard set from the unified extension manifest registry (LMCP-B1,
+ * lib/extensions/*) rather than a second, hardcoded env-var table. Each
+ * embed-mode provider implements:
  *
  *   read(ref, opts)  → Promise<Item[]>
  *     ref:  source-type string e.g. 'prs', 'issues', 'commits', 'messages'
@@ -11,11 +13,106 @@
  *   write(action)    → Promise<void>   (optional — only mutation providers)
  *     action: { type, channel?, text?, … }
  *
+ * `fromEnv()` reads the merged builtin/user/project manifest tiers, keeps
+ * only `kind: 'data-source'` manifests that declare the `read` capability
+ * and have a registered embed adapter (ADAPTERS below), and gates each on
+ * the credential predicate declared next to that adapter. A manifest with
+ * no adapter entry, or whose credential predicate fails, is never silently
+ * dropped: `fromEnv()` also returns the unavailable set with a reason so
+ * callers (construct status, `describe()`) can surface "configured but
+ * unavailable" instead of a provider that appears to simply not exist.
+ *
  * Providers are registered by name and can be swapped for test doubles.
  */
 
+import { loadManifestsFromDir, mergeManifests, resolveManifestDirs } from '../../extensions/loader.mjs';
+
+/**
+ * Registered embed adapters keyed by unified-manifest id. Each entry names
+ * the module to dynamically import, the aliases to register the instance
+ * under, how to build the constructor options from env, and a credential
+ * predicate over the manifest's own `secretEnvKeys` — so "is this provider
+ * usable" is derived from the manifest's declared keys, not re-hardcoded.
+ *
+ * `credentials` is one of:
+ *   { anyOf: [...] }  — usable if at least one listed env var is set (GitHub)
+ *   { allOf: [...] }  — usable only if every listed env var is set (Jira)
+ */
+const ADAPTERS = {
+  github: {
+    aliases: ['github', 'gh'],
+    credentials: { anyOf: ['GITHUB_TOKEN', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'GH_TOKEN'] },
+    load: () => import('./github.mjs'),
+    build: (mod, env) => new mod.GitHubProvider({
+      token: env.GITHUB_TOKEN || env.GITHUB_PERSONAL_ACCESS_TOKEN || env.GH_TOKEN,
+    }),
+  },
+  slack: {
+    aliases: ['slack'],
+    credentials: { anyOf: ['SLACK_BOT_TOKEN'] },
+    load: () => import('./slack.mjs'),
+    build: (mod, env) => new mod.SlackProvider({
+      token: env.SLACK_BOT_TOKEN,
+      teamId: env.SLACK_TEAM_ID,
+    }),
+  },
+  linear: {
+    aliases: ['linear'],
+    credentials: { anyOf: ['LINEAR_API_KEY'] },
+    load: () => import('./linear.mjs'),
+    build: (mod, env) => new mod.LinearProvider({
+      apiKey: env.LINEAR_API_KEY,
+    }),
+  },
+  'atlassian-jira': {
+    aliases: ['jira', 'atlassian'],
+    credentials: { allOf: ['JIRA_BASE_URL', 'JIRA_EMAIL', 'JIRA_API_TOKEN'] },
+    load: () => import('./jira.mjs'),
+    build: (mod, env) => new mod.JiraProvider({
+      baseUrl: env.JIRA_BASE_URL,
+      email: env.JIRA_EMAIL,
+      token: env.JIRA_API_TOKEN,
+    }),
+  },
+};
+
+function credentialStatus(predicate, env) {
+  if (!predicate) return { ok: true, missing: [] };
+  if (predicate.anyOf) {
+    const ok = predicate.anyOf.some((key) => !!env[key]);
+    return { ok, missing: ok ? [] : predicate.anyOf };
+  }
+  if (predicate.allOf) {
+    const missing = predicate.allOf.filter((key) => !env[key]);
+    return { ok: missing.length === 0, missing };
+  }
+  return { ok: true, missing: [] };
+}
+
+/**
+ * Load the merged data-source manifests (builtin < user < project tiers)
+ * that also carry a registered embed adapter. Manifests for kinds embed
+ * mode cannot use (e.g. ingestion-provider) are excluded here rather than
+ * downstream, so every caller of this helper sees the same candidate set.
+ */
+function candidateManifests(rootDir) {
+  const { builtin, user, project } = resolveManifestDirs({ rootDir });
+  const { manifests: builtinManifests } = loadManifestsFromDir(builtin);
+  const { manifests: userManifests } = loadManifestsFromDir(user);
+  const { manifests: projectManifests } = loadManifestsFromDir(project);
+  const merged = mergeManifests(builtinManifests, userManifests, projectManifests);
+
+  return merged.filter((m) => (
+    m.kind === 'data-source' &&
+    Array.isArray(m.capabilities) &&
+    m.capabilities.includes('read') &&
+    Object.prototype.hasOwnProperty.call(ADAPTERS, m.id)
+  ));
+}
+
 export class ProviderRegistry {
   #providers = new Map();
+  #unavailable = [];
 
   /**
    * Register a provider under one or more names.
@@ -68,46 +165,56 @@ export class ProviderRegistry {
   }
 
   /**
-   * Build a registry pre-populated with all concrete providers derived
-   * from the supplied environment. Providers whose required credentials
-   * are absent are silently omitted — callers get a warning at runtime
-   * when a source references a missing provider.
+   * Manifest-declared data-source providers this registry knows about but
+   * did not register — each entry names why, so status surfaces render
+   * "configured but unavailable" instead of the provider vanishing.
+   * @returns {{ id: string, displayName: string, reason: string }[]}
+   */
+  unavailable() {
+    return this.#unavailable;
+  }
+
+  /**
+   * Build a registry pre-populated with every unified-registry data-source
+   * manifest (LMCP-B1, lib/extensions/*) that declares the `read` capability
+   * and has a registered embed adapter, gated on that adapter's credential
+   * predicate. Providers whose required credentials are absent are not
+   * registered but are recorded in `unavailable()` with a reason — callers
+   * get an explicit "configured but unavailable" signal rather than a
+   * provider that silently doesn't exist.
    *
    * @param {object} env  - Merged environment (loadConstructEnv output)
+   * @param {object} [opts]
+   * @param {string} [opts.rootDir] - Project root for project-tier manifests
    * @returns {Promise<ProviderRegistry>}
    */
-  static async fromEnv(env = process.env) {
+  static async fromEnv(env = process.env, { rootDir = process.cwd() } = {}) {
     const registry = new ProviderRegistry();
 
-    if (env.GITHUB_TOKEN || env.GITHUB_PERSONAL_ACCESS_TOKEN) {
-      const { GitHubProvider } = await import('./github.mjs');
-      registry.register(['github', 'gh'], new GitHubProvider({
-        token: env.GITHUB_TOKEN || env.GITHUB_PERSONAL_ACCESS_TOKEN,
-      }));
-    }
-
-    if (env.SLACK_BOT_TOKEN) {
-      const { SlackProvider } = await import('./slack.mjs');
-      registry.register(['slack'], new SlackProvider({
-        token: env.SLACK_BOT_TOKEN,
-        teamId: env.SLACK_TEAM_ID,
-      }));
-    }
+    for (const manifest of candidateManifests(rootDir)) {
+      const adapter = ADAPTERS[manifest.id];
+      const { ok, missing } = credentialStatus(adapter.credentials, env);
 
-    if (env.LINEAR_API_KEY) {
-      const { LinearProvider } = await import('./linear.mjs');
-      registry.register(['linear'], new LinearProvider({
-        apiKey: env.LINEAR_API_KEY,
-      }));
-    }
+      if (!ok) {
+        registry.#unavailable.push({
+          id: manifest.id,
+          displayName: manifest.id,
+          reason: `missing credentials: ${missing.join(', ')}`,
+        });
+        continue;
+      }
 
-    if (env.JIRA_API_TOKEN && env.JIRA_USER_EMAIL && env.JIRA_BASE_URL) {
-      const { JiraProvider } = await import('./jira.mjs');
-      registry.register(['jira', 'atlassian'], new JiraProvider({
-        baseUrl: env.JIRA_BASE_URL,
-        email: env.JIRA_USER_EMAIL,
-        token: env.JIRA_API_TOKEN,
-      }));
+      try {
+        const mod = await adapter.load();
+        const instance = adapter.build(mod, env);
+        registry.register(adapter.aliases, instance);
+      } catch (err) {
+        registry.#unavailable.push({
+          id: manifest.id,
+          displayName: manifest.id,
+          reason: `adapter failed to load: ${err.message}`,
+        });
+      }
     }
 
     return registry;

package/lib/embedded-contract/capability.mjs

@@ -100,6 +100,10 @@ function buildModels(env) {
     local: f.local,
     requiresEnv: f.requiresEnv,
     configured: f.configured,
+    // `configured` is a presence check (env/op:// ref/CLI session found), not proof
+    // the credential authenticates — deep verification is the opt-in provider probe
+    // (construct doctor --probe-providers / orchestrate preflight --probe).
+    configuredBasis: 'presence',
     healthStatus: 'unknown',
   }));
   const tiers = resolveModelTiers({ env });

package/lib/embedded-contract/execution.mjs

@@ -162,7 +162,7 @@ export function resolveExecution(request = {}, { env = process.env, cwd = proces
   let degradationReason = null;
   if (!orchestrationAvailable) {
     degraded = true;
-    degradationReason = `Model could not be resolved; orchestration requires a runnable model — ${modelResolution.error?.reason || 'no model available'}.`;
+    degradationReason = `Model could not be resolved; orchestration requires a runnable model — ${(modelResolution.error?.reason || 'no model available').replace(/\.$/, '')}.`;
   } else if (requestedStrategy === 'orchestrated') {
     degraded = true;
     degradationReason = `Orchestration was requested but no orchestration plan is available${workflowType ? ` for workflowType "${workflowType}"` : ''}.`;

package/lib/embedded-contract/model-resolve.mjs

@@ -15,7 +15,14 @@
  * claims provider health it cannot verify (`healthStatus` defaults to unknown).
  */
 
-import { describeModelFamily, listModelFamilies } from '../model-router.mjs';
+import {
+  defaultModelRegistryPath,
+  describeModelFamily,
+  formatModelResolutionNotices,
+  isModelAvailable,
+  listModelFamilies,
+  resolveValidatedModel,
+} from '../model-router.mjs';
 import { resolveModelTiers } from '../model-registry.mjs';
 import { resolveProviderCapabilitiesSync } from '../provider-capabilities.js';
 
@@ -158,9 +165,24 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
     });
   }
 
-  const tiers = resolveModelTiers({ env, registryPath });
+  const tiers = resolveModelTiers({ env, registryPath: registryPath ?? defaultModelRegistryPath(env) });
   const defaultModel = tiers.models[tier];
   if (defaultModel) {
+    // The env/registry tier pin is a preference, not blind truth: validate it
+    // against the retired-slug denylist and provider-configured catalog before
+    // emitting it, so a stale pin (e.g. a retired Anthropic slug) surfaces a
+    // named warning instead of resolving silently (construct-uccl.4). Route
+    // through resolveValidatedModel so a rejected pin also surfaces a
+    // catalog-wide recommended replacement, not just the rejection notice.
+    const validation = isModelAvailable(defaultModel, { env, strictPin: true });
+    if (!validation.ok) {
+      const validated = resolveValidatedModel({ env, requested: defaultModel });
+      for (const notice of validated.notices) warnings.push(notice);
+      if (!validated.notices.length) {
+        for (const notice of formatModelResolutionNotices({ rejected: validation })) warnings.push(notice);
+      }
+    }
+
     const fallbackReason = hadHostContext
       ? 'Host context could not be honored within its family; used the Construct tier default after cross-provider fallback was permitted.'
       : 'No host context supplied; used the Construct tier default.';
@@ -178,10 +200,38 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
     });
   }
 
+  // No pin resolved (env/registry tier-default came back empty). Before
+  // degrading, check whether ANY provider family has a credential configured
+  // and fall back to that family's tier default — the remediation on the
+  // config-error path ("configure a provider credential") is otherwise
+  // unfollowable, since this path never consulted credentials at all
+  // (construct-uccl.2). An explicit pin always wins over this fallback
+  // because it is only reached once resolveModelTiers found no pin.
+  const configuredFamily = listModelFamilies({ env, allowAmbient }).find((f) => f.configured && f.tiers[tier]);
+  if (configuredFamily) {
+    const model = configuredFamily.tiers[tier];
+    warnings.push(
+      `Model tier '${tier}' is unpinned; using ${model} from the ${configuredFamily.id} credential family. `
+      + `Pin with CX_MODEL_${tier.toUpperCase()} to override.`,
+    );
+    return success({
+      selectedModel: model,
+      family: configuredFamily,
+      tier,
+      resolutionSource: 'credential-family-fallback',
+      fallbackReason: `No tier pin configured; resolved the ${tier} model from the ${configuredFamily.id} credential family.`,
+      tierSource: 'credential-family-fallback',
+      capabilities,
+      warnings,
+      env,
+      allowAmbient,
+    });
+  }
+
   return configError({
     tier,
     reason: `No model could be resolved for the ${tier} tier.`,
-    remediation: 'Set CX_MODEL_REASONING/STANDARD/FAST or configure a provider credential.',
+    remediation: `Set CX_MODEL_${tier.toUpperCase()}=<provider/model>, or configure a provider credential such as ANTHROPIC_API_KEY / OPENROUTER_API_KEY, then rerun`,
     warnings,
   });
 }

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

@@ -1,6 +1,15 @@
 /**
  * lib/embedded-contract/workflow-defs.mjs — embedded workflow type definitions.
  *
+ * Generated/compat shim (LMCP-D2) — this module has no hand-authored catalog.
+ * DEFS is computed at import time exclusively from lib/workflows/loader.mjs
+ * (LMCP-D1), which reads builtin/pack/project *.manifest.json files. Editing a
+ * workflow means editing a manifest under lib/embedded-contract/workflows/ (or a
+ * pack/.cx manifest); this file cannot silently drift from them because it does
+ * not store data of its own. scripts/check-workflow-defs-drift.mjs enforces that
+ * invariant in CI — it fails if the source regains a hardcoded catalog entry or
+ * loses the loader import.
+ *
  * The single source of truth for the workflow types an embedding application can
  * invoke. Each definition names a default role chain (real registry role ids), a
  * model tier, a default approval mode, an optional output-schema artifact, and a
@@ -8,80 +17,40 @@
  * selected roles' declared skills (role-facts) so this file never names a skill
  * id that does not exist. Capability discovery reads these definitions so the
  * published workflow list cannot drift from what invocation actually supports.
+ *
+ * INTAKE_TO_WORKFLOW starts from a hand-authored base table (the mapping for
+ * the 11 builtin workflows) and is then extended by every loaded manifest's
+ * optional `intakeType` field (LMCP-D3) — a pack or project workflow
+ * contribution claims or remaps a classifier label by declaring `intakeType`
+ * in its manifest, with no edit to this file. Manifests are applied in
+ * `workflows` array order, which mirrors loader precedence (builtin, then
+ * pack, then project) for overridden ids and appends new project/pack ids
+ * last, so a project-contributed `intakeType` wins ties over the hardcoded
+ * base table.
  */
 
-const DEFS = {
-  'evidence-ingest': {
-    tier: 'fast',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['researcher', 'data-analyst'],
-    outputSchema: null,
-    description: 'Ingest and structure raw evidence (notes, documents, signals) into a normalized summary.',
-  },
-  'proposal-review': {
-    tier: 'standard',
-    defaultApprovalMode: 'requires-human-approval',
-    chain: ['reviewer', 'devil-advocate'],
-    outputSchema: 'review-report',
-    description: 'Review a proposal for correctness, risk, and hidden assumptions before acceptance.',
-  },
-  'prd-draft': {
-    tier: 'standard',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['product-manager', 'architect'],
-    outputSchema: 'decision',
-    description: 'Draft a product requirements document from a problem statement and supporting evidence.',
-  },
-  'architecture-review': {
-    tier: 'reasoning',
-    defaultApprovalMode: 'requires-human-approval',
-    chain: ['architect', 'security', 'devil-advocate'],
-    outputSchema: 'review-report',
-    description: 'Review an architecture or design for trade-offs, failure modes, and security exposure.',
-  },
-  'risk-review': {
-    tier: 'reasoning',
-    defaultApprovalMode: 'requires-human-approval',
-    chain: ['devil-advocate', 'security', 'legal-compliance'],
-    outputSchema: 'review-report',
-    description: 'Stress-test a plan for risk: failure modes, security, and compliance exposure.',
-  },
-  'research-synthesis': {
-    tier: 'reasoning',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['researcher', 'data-analyst', 'evaluator'],
-    outputSchema: null,
-    description: 'Synthesize multiple sources into a cited, evidence-graded research summary.',
-  },
-  'transcript-process': {
-    tier: 'fast',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['researcher', 'data-analyst'],
-    outputSchema: null,
-    description: 'Process a meeting/call transcript into a summary, decisions, and action items.',
-  },
-  'data-structure': {
-    tier: 'standard',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['data-analyst', 'data-engineer'],
-    outputSchema: null,
-    description: 'Parse, validate, and profile a raw dataset into a structured, described shape.',
-  },
-  'memo-draft': {
-    tier: 'fast',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['docs-keeper', 'reviewer'],
-    outputSchema: null,
-    description: 'Draft a decision or status memo from a problem statement and context.',
-  },
-  'structure-notes': {
-    tier: 'fast',
-    defaultApprovalMode: 'proposal-only',
-    chain: ['orchestrator', 'researcher'],
+import { loadAllWorkflows } from '../workflows/loader.mjs';
+
+const { workflows } = loadAllWorkflows();
+
+// Embed manifests are a workflow-manifest specialization (an embed capability,
+// discovered by the embed-capability loader) — they carry an embed block, no
+// executable role chain — so they are excluded from the invokable workflow-type
+// catalog rather than surfaced as a chain-less workflow.
+const DEFS = {};
+for (const wf of workflows) {
+  if (wf.type === 'embed') continue;
+  DEFS[wf.id] = {
+    tier: wf.tier || 'standard',
+    defaultApprovalMode: wf.defaultApprovalMode,
+    chain: wf.roleChain || [],
     outputSchema: null,
-    description: 'Structure an unclassified brain-dump or rough notes into a normalized summary with extracted intents.',
-  },
-};
+    description: wf.description || '',
+  };
+  if (wf.outputSchema?.artifact) {
+    DEFS[wf.id].outputSchema = wf.outputSchema.artifact;
+  }
+}
 
 // Maps a classifier intakeType to the workflow type that would carry it out, so
 // the triage contract can suggest a directly-invokable workflow. Returns null
@@ -106,6 +75,12 @@ const INTAKE_TO_WORKFLOW = {
   unknown: 'structure-notes',
 };
 
+for (const wf of workflows) {
+  if (typeof wf.intakeType === 'string' && wf.intakeType) {
+    INTAKE_TO_WORKFLOW[wf.intakeType] = wf.id;
+  }
+}
+
 export const WORKFLOW_TYPES = Object.keys(DEFS);
 
 export function getWorkflowDef(type) {
@@ -117,9 +92,9 @@ export function getWorkflowDef(type) {
  * @returns {Array<object>}
  */
 export function listWorkflowDefs() {
-  return WORKFLOW_TYPES.map((type) => ({ type, ...DEFS[type] }));
+  return Object.entries(DEFS).map(([type, def]) => ({ type, ...def }));
 }
 
 export function workflowTypeForIntake(intakeType) {
   return INTAKE_TO_WORKFLOW[intakeType] || null;
-}
+}