@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/providers/filter-audit.mjs

@@ -0,0 +1,68 @@
+/**
+ * lib/providers/filter-audit.mjs — per-poll provider filter audit log.
+ *
+ * ADR-0060 requires every poll to record, per source, the filter that was
+ * enforced and how many items it dropped. Appends one JSONL line per source
+ * per poll to `<rootDir>/.cx/providers/filter-audit.jsonl` with the
+ * acceptance-criteria field names `{provider, instance, filterHash, matched,
+ * dropped}`, plus the ADR's own `fetched`/`admitted` and `pushdown` fields
+ * for the fuller audit shape. Rotation uses `appendWithRotationSync`
+ * directly (not the shared `appendBounded` channel registry) to keep this
+ * change scoped to `lib/providers/*`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { appendWithRotationSync } from '../logging/rotate.mjs';
+
+const AUDIT_SUBDIR = ['.cx', 'providers'];
+const AUDIT_FILE = 'filter-audit.jsonl';
+
+// 10 MB per shard, 5 shards kept — a filter-audit line is written once per
+// source per poll, so this comfortably covers years of daemon uptime.
+
+const MAX_BYTES = 10 * 1024 * 1024;
+const MAX_SEGMENTS = 5;
+
+export function filterAuditPath(rootDir) {
+  return join(rootDir, ...AUDIT_SUBDIR, AUDIT_FILE);
+}
+
+/**
+ * Append one filter-audit record. `matched`/`dropped` are the
+ * acceptance-criteria field names; `fetched`/`admitted` mirror the ADR-0060
+ * audit shape (`admitted` === `matched`) so both vocabularies are queryable
+ * from the same line without a reader needing to know which one shipped.
+ */
+export function recordFilterAudit(rootDir, {
+  provider,
+  instance = null,
+  filterHash: hash = null,
+  scope = null,
+  predicates = null,
+  nativeQuery = null,
+  pushdown = false,
+  fetched,
+  matched,
+}) {
+  const record = {
+    ts: new Date().toISOString(),
+    provider,
+    instance,
+    filterHash: hash,
+    filterApplied: { scope, predicates, nativeQuery, pushdown, fetched, admitted: matched },
+    matched,
+    dropped: fetched - matched,
+  };
+  appendWithRotationSync(filterAuditPath(rootDir), JSON.stringify(record) + '\n', {
+    maxBytes: MAX_BYTES,
+    maxSegments: MAX_SEGMENTS,
+  });
+  return record;
+}
+
+export function readFilterAudit(rootDir) {
+  const path = filterAuditPath(rootDir);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}

package/lib/providers/filter-schema.mjs

@@ -0,0 +1,54 @@
+/**
+ * lib/providers/filter-schema.mjs — provider filter block JSON schema (ADR-0060).
+ *
+ * Ships the normalized filter grammar every provider kind may accept:
+ * `scope` (per-kind container allowlist), `predicates` (portable field-level
+ * filter core), and `nativeQuery` (provider-native passthrough escape hatch).
+ * Per-kind manifest `configSchema` fields reference this via `$ref`; per-kind
+ * `SCOPE_FIELDS_BY_PROVIDER` in `lib/providers/contract.mjs` declares which
+ * `scope` keys a given provider kind actually honors.
+ *
+ * Data-only module (schema + enums), consumed by `validateFilterConfig()`
+ * in `lib/providers/contract.mjs`. No JSON-Schema engine runs here — the
+ * shape below is the source of truth the hand-rolled validator checks
+ * against, keeping schema and validator from drifting silently apart.
+ */
+
+export const FILTER_SCHEMA = Object.freeze({
+  $id: 'construct:provider-filter',
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    scope: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        projects: { type: 'array', items: { type: 'string' } },
+        repos: { type: 'array', items: { type: 'string' } },
+        repoGlob: { type: 'array', items: { type: 'string' } },
+        channels: { type: 'array', items: { type: 'string' } },
+        spaces: { type: 'array', items: { type: 'string' } },
+      },
+    },
+    predicates: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        assignee: { type: 'array', items: { type: 'string' } },
+        statusCategory: { type: 'array', items: { enum: ['to-do', 'in-progress', 'done'] } },
+        priority: { type: 'array', items: { type: 'string' } },
+        label: { type: 'array', items: { type: 'string' } },
+        updatedSince: { type: 'string' },
+      },
+    },
+    nativeQuery: { type: 'string' },
+  },
+});
+
+export const SCOPE_KEYS = Object.freeze(['projects', 'repos', 'repoGlob', 'channels', 'spaces']);
+
+export const PREDICATE_KEYS = Object.freeze(['assignee', 'statusCategory', 'priority', 'label', 'updatedSince']);
+
+export const STATUS_CATEGORIES = Object.freeze(['to-do', 'in-progress', 'done']);
+
+export const TOP_LEVEL_KEYS = Object.freeze(['scope', 'predicates', 'nativeQuery']);

package/lib/providers/github/index.mjs

@@ -14,10 +14,21 @@
  * The provider is intentionally narrow in v1 — issue + PR + code search +
  * a single repo metadata read. Webhook signature verification is in place
  * so consumers can mount a receiver without re-implementing it.
+ *
+ * Scope enforcement: when `repoAllowlist` or `repoAllowGlob` is present in
+ * config, `read()` validates `config.repo` and `search()` validates every
+ * `repo:` qualifier in the query through `validateAllowlist()`
+ * (lib/providers/contract.mjs) before any network call, throwing a typed
+ * `OUT_OF_SCOPE` error on a blocked target. A search query with no `repo:`
+ * qualifier is rejected outright when an allowlist is configured — an
+ * unscoped query could otherwise span the whole credential's visible
+ * surface and defeat the allowlist.
  */
 
 import crypto from 'node:crypto';
 
+import { validateAllowlist } from '../contract.mjs';
+
 const API = 'https://api.github.com';
 
 function authHeader(env) {
@@ -25,6 +36,10 @@ function authHeader(env) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
 
+function outOfScopeError(reason) {
+  return Object.assign(new Error(reason), { code: 'OUT_OF_SCOPE' });
+}
+
 async function ghFetch(pathOrUrl, env, init = {}) {
   const url = pathOrUrl.startsWith('http') ? pathOrUrl : `${API}${pathOrUrl}`;
   const headers = {
@@ -83,6 +98,8 @@ export function create({ env = process.env } = {}) {
 
     async read(config) {
       if (!config?.repo) throw new Error('github.read: config.repo required (owner/name)');
+      const check = validateAllowlist('github', config.repo, config);
+      if (!check.allowed) throw outOfScopeError(check.reason);
       return ghFetch(`/repos/${config.repo}`, env);
     },
 
@@ -90,6 +107,20 @@ export function create({ env = process.env } = {}) {
       const kind = config?.kind || 'issues';
       const query = config?.query;
       if (!query) throw new Error('github.search: config.query required');
+
+      const hasAllowlistConfig = (Array.isArray(config?.repoAllowlist) && config.repoAllowlist.length > 0)
+        || (typeof config?.repoAllowGlob === 'string' && config.repoAllowGlob.length > 0);
+      const repoQualifiers = [...query.matchAll(/\brepo:(\S+)/g)].map((m) => m[1]);
+
+      if (hasAllowlistConfig && repoQualifiers.length === 0) {
+        throw outOfScopeError('github.search: repoAllowlist/repoAllowGlob is configured; query must include a repo: qualifier to enforce scope');
+      }
+      for (const repo of repoQualifiers) {
+        const target = repo.includes('/') ? repo.split('/').pop() : repo;
+        const check = validateAllowlist('github', target, config);
+        if (!check.allowed) throw outOfScopeError(check.reason);
+      }
+
       const path = kind === 'code'
         ? `/search/code?q=${encodeURIComponent(query)}`
         : kind === 'prs'

package/lib/providers/instance-config.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/providers/instance-config.mjs — provider instance config persistence + validation.
+ *
+ * Backs `construct provider add|configure` (LMCP-B12). An "instance config"
+ * is the per-project, per-provider-id settings block (Jira project keys,
+ * GitHub repo, Slack channel, plus the ADR-0060 `filter` block) — distinct
+ * from `lib/providers/registry.mjs`'s `.cx/providers.json`, which registers
+ * *which provider module* answers for an id, not its call-time config.
+ *
+ * Storage: one JSON file per provider id at `<rootDir>/.cx/providers/<id>.json`,
+ * `{ providerId, config, updatedAt }`. Human-reviewable, git-trackable, and
+ * namespaced per id so concurrent `configure` calls on different providers
+ * never collide on one shared file.
+ *
+ * Validation walks the provider's `configSchema` (a JSON-Schema draft
+ * 2020-12 subset: `type`, `properties`, `required`, `enum`, `pattern`,
+ * `minimum`/`maximum`, `additionalProperties`) by hand — no schema engine
+ * dependency, mirroring the hand-rolled approach `contract.mjs` already
+ * takes for the ADR-0060 filter block. `config.filter`, when present, is
+ * delegated to `validateFilterConfig()` from `contract.mjs` (LMCP-B11) so
+ * the two validators can never drift on filter-block semantics. Every
+ * rejection carries a JSON-Pointer-style path (`config.<field>` or
+ * `config.filter.<...>`) so the caller can name the offending key.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { validateFilterConfig } from './contract.mjs';
+import { SCOPE_KEYS, PREDICATE_KEYS } from './filter-schema.mjs';
+
+// `filter.scope.*` and most `filter.predicates.*` leaves are always arrays
+// per the ADR-0060 grammar (filter-schema.mjs); `updatedSince` is the one
+// scalar-string predicate. A single `--filter.scope.projects ABC` must
+// therefore land as `["ABC"]`, not the bare string, even on first occurrence.
+const ALWAYS_ARRAY_FILTER_LEAVES = new Set([
+  ...SCOPE_KEYS.map((k) => `filter.scope.${k}`),
+  ...PREDICATE_KEYS.filter((k) => k !== 'updatedSince').map((k) => `filter.predicates.${k}`),
+]);
+
+export function instanceConfigPath(rootDir, providerId) {
+  return join(rootDir, '.cx', 'providers', `${providerId}.json`);
+}
+
+export function readInstanceConfig(rootDir, providerId) {
+  const filePath = instanceConfigPath(rootDir, providerId);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+export function writeInstanceConfig(rootDir, providerId, config) {
+  const filePath = instanceConfigPath(rootDir, providerId);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const record = { providerId, config, updatedAt: new Date().toISOString() };
+  writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+  return record;
+}
+
+/**
+ * Build the default config object from a JSON-Schema `properties` map:
+ * every property that declares a `default` is seeded with it. Properties
+ * without a default are omitted — `provider add` scaffolds only what the
+ * schema actually commits to, not placeholder nulls.
+ */
+export function defaultsFromSchema(configSchema) {
+  const defaults = {};
+  const properties = configSchema?.properties || {};
+  for (const [key, propSchema] of Object.entries(properties)) {
+    if (propSchema && Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
+      defaults[key] = propSchema.default;
+    }
+  }
+  return defaults;
+}
+
+function typeMatches(value, type) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return typeof value === 'number' && Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array': return Array.isArray(value);
+    case 'object': return value !== null && typeof value === 'object' && !Array.isArray(value);
+    default: return true;
+  }
+}
+
+/**
+ * Validate one property value against its JSON-Schema property descriptor.
+ * Returns an array of error strings (empty when valid); each string is
+ * prefixed with `path` so nested callers can build a JSON-Pointer trail.
+ */
+function validateProperty(path, value, propSchema) {
+  const errors = [];
+  if (!propSchema) return errors;
+
+  if (propSchema.enum && !propSchema.enum.includes(value)) {
+    errors.push(`${path}: must be one of [${propSchema.enum.join(', ')}], got ${JSON.stringify(value)}`);
+    return errors;
+  }
+
+  if (propSchema.type && !typeMatches(value, propSchema.type)) {
+    errors.push(`${path}: must be of type ${propSchema.type}, got ${JSON.stringify(value)}`);
+    return errors;
+  }
+
+  if (propSchema.pattern && typeof value === 'string' && !new RegExp(propSchema.pattern).test(value)) {
+    errors.push(`${path}: does not match pattern ${propSchema.pattern}`);
+  }
+
+  if (typeof value === 'number') {
+    if (propSchema.minimum !== undefined && value < propSchema.minimum) {
+      errors.push(`${path}: must be >= ${propSchema.minimum}, got ${value}`);
+    }
+    if (propSchema.maximum !== undefined && value > propSchema.maximum) {
+      errors.push(`${path}: must be <= ${propSchema.maximum}, got ${value}`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a merged instance config against a provider's declared
+ * `configSchema`, plus (when the config carries a `filter` key) the
+ * ADR-0060 filter block via `validateFilterConfig()`. Returns
+ * `{ valid: true }` or `{ valid: false, errors: string[] }` — never throws,
+ * so callers (CLI + tests) get a uniform result shape to report from.
+ *
+ * `filter` is accepted on every provider config regardless of whether the
+ * schema's `properties` declares it: the ADR-0060 block is a cross-cutting
+ * concern layered on top of the provider-specific schema, not a provider-
+ * specific property.
+ */
+export function validateInstanceConfig(providerId, configSchema, config = {}) {
+  const errors = [];
+  const schema = configSchema || {};
+  const properties = schema.properties || {};
+  const { filter, ...rest } = config || {};
+
+  for (const required of schema.required || []) {
+    if (!(required in rest)) {
+      errors.push(`config.${required}: required property missing`);
+    }
+  }
+
+  for (const [key, value] of Object.entries(rest)) {
+    const path = `config.${key}`;
+    if (!(key in properties)) {
+      if (schema.additionalProperties === false) {
+        errors.push(`${path}: unknown property (not declared in configSchema)`);
+      }
+      continue;
+    }
+    errors.push(...validateProperty(path, value, properties[key]));
+  }
+
+  if (filter !== undefined) {
+    try {
+      validateFilterConfig(providerId, filter);
+    } catch (err) {
+      errors.push(`config.filter: ${err.message}`);
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors };
+  return { valid: true };
+}
+
+/**
+ * Apply `--key value` CLI overrides onto a base config object. Dotted keys
+ * (`scope.projects`) address nested objects; repeated flags for an array
+ * leaf (`filter.scope.projects`) accumulate rather than overwrite, so
+ * `--filter.scope.projects ABC --filter.scope.projects DEF` yields
+ * `["ABC", "DEF"]` in one `configure` call.
+ */
+export function applyOverrides(base, overrides) {
+  const result = JSON.parse(JSON.stringify(base || {}));
+
+  // Accumulation only fires for a keyPath repeated within *this* override
+  // batch — a pre-existing base value (a schema default or a prior
+  // `configure` call) is a plain overwrite, never folded into an array.
+  const touched = new Set();
+
+  for (const { keyPath, value } of overrides) {
+    const segments = keyPath.split('.');
+    let cursor = result;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i];
+      if (typeof cursor[segment] !== 'object' || cursor[segment] === null || Array.isArray(cursor[segment])) {
+        cursor[segment] = {};
+      }
+      cursor = cursor[segment];
+    }
+    const leaf = segments[segments.length - 1];
+    const parsed = parseFlagValue(value);
+    if (touched.has(keyPath)) {
+      cursor[leaf] = Array.isArray(cursor[leaf]) ? [...cursor[leaf], parsed] : [cursor[leaf], parsed];
+    } else if (ALWAYS_ARRAY_FILTER_LEAVES.has(keyPath)) {
+      cursor[leaf] = [parsed];
+      touched.add(keyPath);
+    } else {
+      cursor[leaf] = parsed;
+      touched.add(keyPath);
+    }
+  }
+  return result;
+}
+
+function parseFlagValue(raw) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw !== '' && !Number.isNaN(Number(raw))) return Number(raw);
+  return raw;
+}

package/lib/providers/op-locate.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/providers/op-locate.mjs — resolve the 1Password `op` CLI binary once.
+ *
+ * A GUI-launched MCP host (OpenCode, Claude Desktop, Cursor) spawns
+ * `node lib/mcp/server.mjs` with a minimal PATH that omits Homebrew, so a bare
+ * `spawnSync('op', …)` ENOENTs and `op` is misreported as not installed despite
+ * being present at a well-known path like /opt/homebrew/bin/op. Resolution walks three
+ * tiers — the process PATH (cheap, no shell), then a login-shell probe that re-runs
+ * the user's rc/profile (macOS path_helper included, the way credential-bootstrap
+ * recovers PATH), then well-known install dirs — and caches the absolute path for
+ * the process lifetime. Every op-invocation site (secret-resolver, op-run,
+ * credential-bootstrap) resolves through here so PATH semantics stay consistent
+ * across call sites. env/runShell/wellKnown are injectable so tests exercise each
+ * tier without a real 1Password install.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const WELL_KNOWN_POSIX = ['/opt/homebrew/bin/op', '/usr/local/bin/op', '/usr/bin/op'];
+
+function wellKnownWin32() {
+  const local = process.env.LOCALAPPDATA;
+  return [
+    local ? path.join(local, 'Microsoft', 'WinGet', 'Links', 'op.exe') : null,
+    'C:\\ProgramData\\chocolatey\\bin\\op.exe',
+  ].filter(Boolean);
+}
+
+function defaultWellKnown() {
+  return process.platform === 'win32' ? wellKnownWin32() : WELL_KNOWN_POSIX;
+}
+
+let cached;
+
+function isFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Scan the process PATH for `op` without spawning a shell — the common case where
+// PATH is already correct resolves here at no cost.
+
+function scanProcessPath(env) {
+  const dirs = String(env?.PATH || '').split(path.delimiter).filter(Boolean);
+  const names = process.platform === 'win32' ? ['op.exe', 'op.cmd', 'op.bat'] : ['op'];
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (isFile(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+// Login-shell probe: `sh -lc 'command -v op'` re-runs the user's shell init, which
+// on macOS is where path_helper adds Homebrew — recovering the PATH a GUI-launched
+// child never inherited. `where op` is the Windows analogue.
+
+function defaultRunShell() {
+  if (process.platform === 'win32') {
+    const r = spawnSync('where', ['op'], { encoding: 'utf8', timeout: 3000 });
+    return r.status === 0 ? String(r.stdout || '').split(/\r?\n/)[0].trim() : '';
+  }
+  const r = spawnSync('sh', ['-lc', 'command -v op'], { encoding: 'utf8', timeout: 3000 });
+  return r.status === 0 ? String(r.stdout || '').trim() : '';
+}
+
+/**
+ * Resolve the `op` binary (process PATH → login-shell PATH → well-known dirs),
+ * returning an absolute path or null. Cached for the process lifetime; pass
+ * fresh:true to bypass the cache. env/runShell/wellKnown are injectable for tests.
+ */
+export function locateOpBinary({ env = process.env, runShell = defaultRunShell, wellKnown = defaultWellKnown(), fresh = false } = {}) {
+  if (!fresh && cached !== undefined) return cached;
+
+  const onPath = scanProcessPath(env);
+  if (onPath) return (cached = onPath);
+
+  const viaShell = runShell();
+  if (viaShell && isFile(viaShell)) return (cached = viaShell);
+
+  for (const candidate of wellKnown) {
+    if (candidate && isFile(candidate)) return (cached = candidate);
+  }
+
+  return (cached = null);
+}
+
+export function __resetOpLocateCache() {
+  cached = undefined;
+}

package/lib/providers/op-run.mjs

@@ -1,13 +1,21 @@
 /**
- * lib/providers/op-run.mjs — optionally launch a child under 1Password `op run`.
+ * lib/providers/op-run.mjs — optionally launch Construct under 1Password `op run`.
  *
- * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines)
- * and the `op` CLI is installed, long-lived Construct services are spawned through
- * `op run --env-file <file> -- <cmd>`, so op:// references resolve once at startup
- * into the process env. lib/service-manager.mjs calls wrapWithOpRun at each service
- * spawn, so the memory server, OpenCode, the copilot bridge, the doctor daemon, and
- * the oracle daemon all inherit resolved provider keys without a per-invocation
- * shell wrapper. Masking stays on so resolved secrets are not echoed to service logs.
+ * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines) and
+ * the `op` CLI is installed, `construct dev` re-execs itself once under
+ * `op run --env-file <file> -- …` (maybeReExecUnderOpRun). Every op:// reference then
+ * resolves a single time at that stable parent — one biometric unlock — and the
+ * detached daemons the re-exec'd process spawns inherit the resolved keys through the
+ * parent env. A CONSTRUCT_OP_RUN_ACTIVE sentinel marks the wrapped process so nested
+ * launches inside it do not re-wrap and re-prompt.
+ *
+ * wrapWithOpRun stays the per-service fallback for daemons started outside the
+ * re-exec'd parent (a doctor or oracle restart from a hook), where no parent
+ * resolution has run; under the parent (sentinel set) it returns the command
+ * unchanged. The trade-off of resolving once at the parent: `op run` masks the
+ * parent's own stdout but not the separate log files of the daemons it detaches, so a
+ * daemon that echoes a key logs it unmasked (ADR-0049). The per-service fallback still
+ * masks the daemons it wraps directly.
  *
  * Strictly opt-in: with the var unset, the file missing, or `op` absent, the
  * command is returned unchanged and 1Password is never invoked. No other setup
@@ -17,6 +25,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { locateOpBinary } from './op-locate.mjs';
+
+// Set on the process env when Construct has already re-exec'd under a parent `op run`.
+// Both the parent re-exec and the per-service wrap check it so a single resolution at
+// the top of the tree is never nested (which would re-prompt and double-resolve).
+
+export const OP_RUN_ACTIVE_ENV = 'CONSTRUCT_OP_RUN_ACTIVE';
 
 function expandHome(file, homeDir) {
   if (file === '~') return homeDir;
@@ -36,8 +51,10 @@ export function resolveOpEnvFile(env = process.env, homeDir = os.homedir()) {
 }
 
 export function opCliAvailable() {
+  const opPath = locateOpBinary();
+  if (!opPath) return false;
   try {
-    return spawnSync('op', ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
+    return spawnSync(opPath, ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
   } catch {
     return false;
   }
@@ -48,6 +65,10 @@ export function opCliAvailable() {
  * to the original command unchanged otherwise. `hasOp` is injectable for tests.
  */
 export function wrapWithOpRun(command, args = [], { env = process.env, homeDir = os.homedir(), hasOp = opCliAvailable } = {}) {
+  // A parent `op run` already resolved every reference into this env; wrapping again
+  // would spawn a nested op run that re-prompts, so hand back the command untouched.
+  if (env[OP_RUN_ACTIVE_ENV]) return { command, args, wrapped: false, envFile: null };
+
   const file = resolveOpEnvFile(env, homeDir);
   if (!file || !hasOp()) return { command, args, wrapped: false, envFile: null };
   return {
@@ -57,3 +78,37 @@ export function wrapWithOpRun(command, args = [], { env = process.env, homeDir =
     envFile: file,
   };
 }
+
+/**
+ * Re-exec the current process once under `op run` so every op:// reference in the
+ * env-file resolves a single time into the process env; the detached daemons the
+ * re-exec'd process then spawns inherit the resolved keys without their own op run.
+ * The blocking spawnSync makes the outer process a thin wrapper that exits with the
+ * inner status. Returns { reExecuted: false, reason } on every opt-out path — sentinel
+ * already set, no resolvable env-file, `op` absent, or a spawn error — so the caller
+ * falls through to the normal (per-service-wrap) launch unchanged. `spawnFn` and the
+ * process descriptors are injectable for tests.
+ */
+export function maybeReExecUnderOpRun({
+  argv = process.argv,
+  execPath = process.execPath,
+  env = process.env,
+  homeDir = os.homedir(),
+  hasOp = opCliAvailable,
+  spawnFn = spawnSync,
+} = {}) {
+  if (env[OP_RUN_ACTIVE_ENV]) return { reExecuted: false, reason: 'already-active' };
+  const file = resolveOpEnvFile(env, homeDir);
+  if (!file) return { reExecuted: false, reason: 'not-opted-in' };
+  if (!hasOp()) return { reExecuted: false, reason: 'op-missing' };
+
+  const scriptArgs = argv.slice(1);
+  const childEnv = { ...env, [OP_RUN_ACTIVE_ENV]: '1' };
+  const result = spawnFn('op', ['run', `--env-file=${file}`, '--', execPath, ...scriptArgs], {
+    stdio: 'inherit',
+    env: childEnv,
+  });
+  if (result?.error) return { reExecuted: false, reason: 'spawn-failed', error: result.error };
+  const code = typeof result?.status === 'number' ? result.status : 1;
+  return { reExecuted: true, code, envFile: file };
+}

package/lib/providers/registry.mjs

@@ -26,10 +26,20 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { assertProviderContract } from './contract.mjs';
 import { getBreaker } from './circuit-breaker.mjs';
 import { configDir } from '../config/xdg.mjs';
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+import { describeModelProviders } from '../models/catalog.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-export const BUILT_INS = ['github', 'atlassian-jira', 'atlassian-confluence', 'slack', 'salesforce'];
+/**
+ * @deprecated Use manifest-driven provider discovery via resolveProviders() instead.
+ * Will be removed in a future version.
+ */
+export const BUILT_INS = (() => {
+  const { builtin: dir } = resolveManifestDirs();
+  const { manifests } = loadManifestsFromDir(dir);
+  return manifests.filter((m) => m.kind === 'data-source').map((m) => m.id);
+})();
 
 function readJsonIfExists(path) {
   try {
@@ -109,7 +119,13 @@ export async function resolveProviders({ rootDir = process.cwd(), env = process.
   const sources = {};
   const errors = [];
 
-  for (const id of BUILT_INS) {
+  const { builtin: builtinManifestDir } = resolveManifestDirs();
+  const { manifests: allManifests } = loadManifestsFromDir(builtinManifestDir);
+  const builtInIds = allManifests
+    .filter((m) => m.kind === 'data-source')
+    .map((m) => m.id);
+
+  for (const id of builtInIds) {
     try {
       const mod = await loadBuiltIn(id);
       if (!mod) continue;
@@ -145,6 +161,12 @@ export async function resolveProviders({ rootDir = process.cwd(), env = process.
   return { providers, sources, errors };
 }
 
+// kind='model' manifests (LMCP-B4) enumerate through this same registry but
+// are never instantiated as data-source contract instances — model provider
+// families keep their cache/poll/visibility logic in lib/models/catalog.mjs
+// and lib/model-router.mjs. This appends their manifest-derived summary rows
+// so `construct provider list` shows one merged surface across both kinds.
+
 export async function describeProviders({ rootDir = process.cwd(), env = process.env } = {}) {
   const { providers, sources, errors } = await resolveProviders({ rootDir, env });
   const summary = await Promise.all(
@@ -161,7 +183,8 @@ export async function describeProviders({ rootDir = process.cwd(), env = process
       };
     })
   );
-  return { summary, errors };
+  const modelSummary = describeModelProviders({ rootDir, env });
+  return { summary: [...summary, ...modelSummary], errors };
 }
 
 // Standalone validation for a candidate override entry: imports the package