@geraldmaron/construct 1.0.19 → 1.0.21

package/lib/orchestration/runtime.mjs

@@ -0,0 +1,317 @@
+/**
+ * lib/orchestration/runtime.mjs — Construct-owned local orchestration runtime.
+ *
+ * The product goal: hosts are front doors, Construct is the system. A
+ * host that lacks native multi-agent execution should still reach equivalent
+ * Construct outcomes through a Construct-owned runtime rather than depending on
+ * whichever editor exposes the strongest teammate mechanics. This module intakes
+ * a request, plans/decomposes it into a sequenced specialist chain (reusing the
+ * orchestration-policy planner), resolves the execution-capability contract
+ * (reusing resolveExecution), persists a durable run + task lifecycle through a
+ * pluggable run store (filesystem default, sqlite Mode-B, postgres Mode-C), and
+ * emits lifecycle traces.
+ *
+ * Worker backends (ADR-0020, ADR-0021):
+ *   - `inline` (default): OWNS planning, sequencing, handoff state, persistence,
+ *     and observability, and PREPARES each specialist task for a downstream
+ *     executor. It does NOT itself perform specialist LLM reasoning. Tasks reach
+ *     status `prepared`; the prepare-only disclaimer applies.
+ *   - `provider`: EXECUTES each specialist task by calling the configured
+ *     provider/model with the specialist persona prompt. Tasks reach status
+ *     `done` carrying real model output; the prepare-only disclaimer does NOT
+ *     apply to provider-executed tasks. A failing task is recorded (status
+ *     `failed`) and the run completes `completed-with-failures` rather than
+ *     crashing.
+ *
+ * The run reports `workerBackend` and per-task `executor` so a host can never
+ * mistake a prepared task for executed specialist output. When the execution
+ * contract resolves to prompt-only or host-direct, Construct owns no specialist
+ * task sequence and the run records that explicitly.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+import { routeRequest } from '../orchestration-policy.mjs';
+import { resolveExecution } from '../embedded-contract/execution.mjs';
+import { detectHostCapabilities } from '../host-capabilities.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
+import { resolveRunStore } from './store.mjs';
+import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
+
+export const WORKER_BACKENDS = WORKER_BACKEND_SET;
+export const DEFAULT_WORKER_BACKEND = INLINE;
+
+const RUNTIME_SEMANTICS = 'The inline worker backend owns planning, sequencing, handoff state, persistence, and observability, and prepares each specialist task for a downstream executor. It does not perform specialist LLM reasoning itself; tasks reaching status "prepared" are ready for a worker backend or host to execute. The provider worker backend executes specialist reasoning via the configured model and records real output as task.output.';
+
+function newRunId() {
+  return `run-${randomBytes(6).toString('hex')}`;
+}
+
+function truncate(text, max) {
+  const s = String(text || '');
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+// hostRole reports how the calling host orchestrates, so an adapter can decide
+// whether to delegate to Construct's runtime (its reason for being). A direct
+// CLI call has no host; an unrecognized host name is reported as unknown rather
+// than guessed.
+
+function resolveHostRole(hostName) {
+  if (!hostName) return 'cli-direct';
+  const match = detectHostCapabilities().find((h) => h.host.toLowerCase() === String(hostName).toLowerCase());
+  return match ? match.orchestration : 'unknown';
+}
+
+function pickExecution(data) {
+  return {
+    executionMode: data.executionMode,
+    effectiveStrategy: data.effectiveStrategy,
+    requestedStrategy: data.requestedStrategy,
+    constructCapabilitiesActive: data.constructCapabilitiesActive,
+    degraded: data.degraded,
+    degradationReason: data.degradationReason,
+    selectedProvider: data.selectedProvider,
+    selectedModel: data.selectedModel,
+    resolutionSource: data.resolutionSource,
+    orchestrationPlanned: data.orchestrationPlanned,
+    orchestrationAvailable: data.orchestrationAvailable,
+    deploymentMode: data.deploymentMode,
+  };
+}
+
+function buildTasks(route) {
+  const reasons = route.dispatchReasons || {};
+  const handoffByProducer = new Map();
+  for (const edge of route.contractChain || []) {
+    const producer = edge.contract?.producer;
+    if (producer && !handoffByProducer.has(producer)) handoffByProducer.set(producer, edge.contract.id);
+  }
+  return (route.specialists || []).map((role, i) => ({
+    id: `t${i + 1}`,
+    seq: i,
+    role,
+    reason: reasons[role] || null,
+    handoffContract: handoffByProducer.get(role.replace(/^cx-/, '')) || null,
+    status: 'queued',
+    executor: null,
+    output: null,
+    error: null,
+    startedAt: null,
+    finishedAt: null,
+  }));
+}
+
+// The worker backend is a deployment concern: an explicit option wins, then the
+// run's recorded backend, then config (orchestration.workerBackend), then the
+// inline default. An unknown value falls back to inline rather than guessing.
+
+function resolveWorkerBackend({ explicit, run, config }) {
+  const candidate = explicit || run?.workerBackend || config?.orchestration?.workerBackend || DEFAULT_WORKER_BACKEND;
+  return WORKER_BACKENDS.includes(candidate) ? candidate : DEFAULT_WORKER_BACKEND;
+}
+
+function loadConfig(cwd, env) {
+  try {
+    return loadProjectConfig(cwd, env).config || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Plan a run: resolve the execution contract, decompose into a specialist chain,
+ * and persist a durable run record (status `planned`). Pure of model calls.
+ *
+ * @param {object} request
+ * @param {object} [opts]   { env, cwd }
+ * @returns {Promise<object>} the persisted run
+ */
+export async function planRun(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const {
+    request: text = '', workflowType = null, requestedStrategy = 'auto', useConstruct = true,
+    host = null, hostModel = null, hostProvider = null, fileCount = 0, moduleCount = 0,
+  } = request;
+
+  const config = loadConfig(cwd, env);
+  const { store, warnings: storeWarnings } = resolveRunStore({ config, env, cwd });
+
+  const execData = resolveExecution(
+    { workflowType, requestedStrategy, useConstruct, host, hostModel, hostProvider },
+    { env, cwd },
+  );
+  const route = routeRequest({ request: text, fileCount, moduleCount });
+
+  const traceId = newTraceId();
+  const runId = newRunId();
+  const now = new Date().toISOString();
+  const workerBackend = resolveWorkerBackend({ config });
+
+  // Construct owns a specialist task sequence only when the contract resolves to
+  // orchestrated execution; prompt-only and host-direct own none, and the run
+  // records that rather than implying orchestration that did not happen.
+  const orchestrates = execData.effectiveStrategy === 'orchestrated';
+  const tasks = orchestrates ? buildTasks(route) : [];
+
+  const run = {
+    runId,
+    traceId,
+    createdAt: now,
+    updatedAt: now,
+    request: { summary: truncate(text, 200), workflowType, requestedStrategy },
+    hostRole: resolveHostRole(host),
+    workerBackend,
+    execution: pickExecution(execData),
+    plan: {
+      intent: route.intent,
+      track: route.track,
+      specialists: route.specialists || [],
+      dispatchPlan: route.dispatchPlan,
+      contractChain: (route.contractChain || []).map((e) => ({ id: e.contract?.id, producer: e.contract?.producer, consumer: e.contract?.consumer, stage: e.stage })),
+    },
+    tasks,
+    status: 'planned',
+    warnings: [...(execData.warnings || []), ...storeWarnings],
+    semantics: RUNTIME_SEMANTICS,
+    executionSemantics: execData.semantics,
+  };
+
+  await store.saveRun(run);
+  emitTraceEvent({
+    rootDir: cwd, env, traceId, spanId: newSpanId(), eventType: 'task_graph.created',
+    metadata: { runId, executionMode: run.execution.executionMode, specialists: run.plan.specialists, workerBackend: run.workerBackend },
+  });
+  return run;
+}
+
+// The inline backend prepares one task: queued → running → prepared, no model
+// reasoning. The boundary ADR-0020 makes explicit.
+
+function prepareTaskInline(task) {
+  task.executor = 'inline:prepared';
+  task.status = 'prepared';
+  task.finishedAt = new Date().toISOString();
+}
+
+// The provider backend executes one task against the configured model. A failed
+// task is recorded (status `failed`, task.error) and does not abort the run, so
+// one specialist failure cannot lose the work of the others.
+
+async function executeTaskViaProvider(task, run, env, fetchImpl) {
+  try {
+    const result = await runTaskViaProvider({
+      task, run,
+      model: run.execution?.selectedModel,
+      provider: run.execution?.selectedProvider,
+      env, fetchImpl,
+    });
+    task.output = result.output;
+    task.executor = `provider:${result.provider}:${result.model}`;
+    task.status = 'done';
+    task.finishedAt = new Date().toISOString();
+    return true;
+  } catch (err) {
+    task.executor = `provider:error`;
+    task.error = { code: err.code || 'PROVIDER_EXECUTION_FAILED', message: err.message };
+    task.status = 'failed';
+    task.finishedAt = new Date().toISOString();
+    return false;
+  }
+}
+
+/**
+ * Execute a planned run through the chosen worker backend, persisting after each
+ * task transition so the run is resumable and observable.
+ *
+ * @param {string} cwd
+ * @param {string} runId
+ * @param {object} [opts]   { env, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the completed run
+ */
+export async function executeRun(cwd, runId, { env = process.env, workerBackend = null, fetchImpl } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  const run = await store.loadRun(runId);
+  if (!run) {
+    const err = new Error(`Orchestration run not found: ${runId}`);
+    err.code = 'RUN_NOT_FOUND';
+    throw err;
+  }
+
+  const backend = resolveWorkerBackend({ explicit: workerBackend, run, config });
+  run.workerBackend = backend;
+  run.status = 'running';
+  run.updatedAt = new Date().toISOString();
+  await store.saveRun(run);
+
+  let anyFailed = false;
+  for (const task of run.tasks) {
+    task.status = 'running';
+    task.startedAt = new Date().toISOString();
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.started', role: task.role, taskId: task.id, metadata: { runId, workerBackend: backend } });
+
+    if (backend === PROVIDER) {
+      const ok = await executeTaskViaProvider(task, run, env, fetchImpl);
+      if (!ok) anyFailed = true;
+    } else {
+      prepareTaskInline(task);
+    }
+
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: { runId, status: task.status } });
+    run.updatedAt = new Date().toISOString();
+    await store.saveRun(run);
+  }
+
+  run.status = anyFailed ? 'completed-with-failures' : 'completed';
+  run.updatedAt = new Date().toISOString();
+  await store.saveRun(run);
+  emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
+  return run;
+}
+
+/**
+ * Plan and execute in one call (the common `orchestrate run` path).
+ */
+export async function runOrchestration(request = {}, { env = process.env, cwd = process.cwd(), workerBackend = null, fetchImpl } = {}) {
+  const planned = await planRun(request, { env, cwd });
+  return executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl });
+}
+
+/**
+ * The structured metadata a host adapter consumes for runtime-backed integration.
+ */
+export function hostAdapterMetadata(run) {
+  const e = run.execution || {};
+  return {
+    runId: run.runId,
+    traceId: run.traceId,
+    status: run.status,
+    requestedStrategy: e.requestedStrategy,
+    effectiveStrategy: e.effectiveStrategy,
+    executionMode: e.executionMode,
+    constructCapabilitiesActive: e.constructCapabilitiesActive,
+    workerBackend: run.workerBackend,
+    hostRole: run.hostRole,
+    degraded: e.degraded,
+    degradationReason: e.degradationReason,
+    selectedProvider: e.selectedProvider,
+    selectedModel: e.selectedModel,
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor })),
+    warnings: run.warnings || [],
+    semantics: run.semantics,
+    executionSemantics: run.executionSemantics,
+  };
+}
+
+export async function getRun(cwd, runId, { env = process.env } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  return store.loadRun(runId);
+}
+
+export async function getRuns(cwd, { env = process.env, ...opts } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  return store.listRuns(opts);
+}

package/lib/orchestration/store.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/orchestration/store.mjs — run-store resolver for the orchestration runtime.
+ *
+ * One interface — saveRun(run), loadRun(runId), listRuns(opts) — over three
+ * backends: filesystem (Mode-A default, zero dependency), sqlite (Mode-B,
+ * node:sqlite), and postgres (Mode-C, shared team/enterprise store). The runtime
+ * resolves a store through here instead of importing run-store functions
+ * directly, so the backend is a deployment concern rather than a code edit.
+ *
+ * Selection precedence: explicit config (`orchestration.store`) or the
+ * CONSTRUCT_ORCHESTRATION_STORE env override win; otherwise the deployment mode
+ * decides (solo→filesystem, team/enterprise→postgres). When the chosen backend
+ * is unavailable (sqlite on Node <22.5, or postgres with no DATABASE_URL / null
+ * sql client) the resolver falls back to filesystem and records a warning rather
+ * than failing — durability of the default tier is never sacrificed to an
+ * optional one. The returned store is always async-uniform so callers await it
+ * regardless of backend; the filesystem and sqlite backends resolve synchronously
+ * under the hood, so the default Mode-A run record is byte-for-byte unchanged.
+ */
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { createSqlClient } from '../storage/backend.mjs';
+import { saveRun as fsSaveRun, loadRun as fsLoadRun, listRuns as fsListRuns } from './run-store.mjs';
+import { sqliteAvailable, createSqliteRunStore } from './run-store-sqlite.mjs';
+import { PostgresRunStore } from './run-store-postgres.mjs';
+
+export const ORCHESTRATION_STORES = ['filesystem', 'sqlite', 'postgres'];
+export const STORE_ENV_KEY = 'CONSTRUCT_ORCHESTRATION_STORE';
+
+function filesystemStore(cwd) {
+  return {
+    kind: 'filesystem',
+    saveRun: (run) => fsSaveRun(cwd, run),
+    loadRun: (runId) => fsLoadRun(cwd, runId),
+    listRuns: (opts) => fsListRuns(cwd, opts),
+  };
+}
+
+function sqliteStore(cwd) {
+  const store = createSqliteRunStore({ cwd });
+  return {
+    kind: 'sqlite',
+    saveRun: (run) => store.saveRun(run),
+    loadRun: (runId) => store.loadRun(runId),
+    listRuns: (opts) => store.listRuns(opts),
+  };
+}
+
+function postgresStore({ sql, project }) {
+  const store = new PostgresRunStore({ sql, project });
+  let ensured = null;
+  const ready = () => {
+    if (!ensured) ensured = store.ensureSchema();
+    return ensured;
+  };
+  return {
+    kind: 'postgres',
+    saveRun: async (run) => { await ready(); return store.saveRun(run); },
+    loadRun: async (runId) => { await ready(); return store.loadRun(runId); },
+    listRuns: async (opts) => { await ready(); return store.listRuns(opts); },
+  };
+}
+
+function projectKey(config, cwd) {
+  return config?.deployment?.projectName || cwd || 'default';
+}
+
+function chooseBackend({ config, env, cwd }) {
+  const explicit = String(env?.[STORE_ENV_KEY] || config?.orchestration?.store || '').trim().toLowerCase();
+  if (ORCHESTRATION_STORES.includes(explicit)) return explicit;
+  const mode = getDeploymentMode(env, { cwd });
+  return mode === 'solo' ? 'filesystem' : 'postgres';
+}
+
+/**
+ * Resolve a run store for the runtime.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]   loaded project config (reads orchestration.store)
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.cwd]
+ * @returns {{ store: {kind:string, saveRun:Function, loadRun:Function, listRuns:Function}, backend: string, warnings: string[] }}
+ */
+export function resolveRunStore({ config = {}, env = process.env, cwd = process.cwd() } = {}) {
+  const warnings = [];
+  const requested = chooseBackend({ config, env, cwd });
+
+  if (requested === 'sqlite') {
+    if (sqliteAvailable()) return { store: sqliteStore(cwd), backend: 'sqlite', warnings };
+    warnings.push('orchestration.store "sqlite" requires Node >=22.5 (node:sqlite unavailable); falling back to filesystem.');
+    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+  }
+
+  if (requested === 'postgres') {
+    const sql = createSqlClient(env);
+    if (sql) return { store: postgresStore({ sql, project: projectKey(config, cwd) }), backend: 'postgres', warnings };
+    warnings.push('orchestration.store "postgres" requires a reachable DATABASE_URL; falling back to filesystem.');
+    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+  }
+
+  return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+}

package/lib/orchestration/worker.mjs

@@ -0,0 +1,167 @@
+/**
+ * lib/orchestration/worker.mjs — provider-backed worker backend for the local
+ * orchestration runtime.
+ *
+ * The inline backend (runtime.mjs) PREPARES a specialist task and stops short of
+ * model reasoning (ADR-0020). The provider backend closes that gap: it EXECUTES
+ * one specialist task by calling the configured provider/model with the
+ * specialist's persona prompt as system context and the run's request as the
+ * user turn, returning the model's real output (ADR-0021). Because it genuinely
+ * runs the model, the prepare-only disclaimer does not apply to provider-executed
+ * tasks — runtime.mjs records `task.output` and `executor='provider:<provider>:<model>'`
+ * so a host can distinguish prepared from executed work.
+ *
+ * Provider selection mirrors lib/ingest/provider-extract.mjs: Anthropic
+ * `/v1/messages` for Claude-family models, OpenRouter `/v1/chat/completions`
+ * otherwise; key resolution reads env (ANTHROPIC_API_KEY / OPENROUTER_API_KEY)
+ * and augments with ambient dotenv only when the caller did not inject an
+ * explicit env (hermetic-when-explicit). `fetchImpl` is injectable so the path is
+ * exercised end to end against a mock provider without a live key. Failures
+ * surface as structured codes (PROVIDER_KEY_MISSING, PROVIDER_MODEL_UNRESOLVED,
+ * PROVIDER_EXECUTION_FAILED) rather than opaque HTTP errors.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const INLINE = 'inline';
+export const PROVIDER = 'provider';
+export const WORKER_BACKEND_SET = [INLINE, PROVIDER];
+
+const MAX_OUTPUT_TOKENS = 2048;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(HERE, '..', '..', 'specialists', 'prompts');
+
+function providerError(code, reason, remediation) {
+  const err = new Error(reason);
+  err.code = code;
+  err.remediation = remediation;
+  return err;
+}
+
+function isAnthropic(provider, model) {
+  return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
+}
+
+// Key resolution mirrors provider-extract: env first, then the two cheap dotenv
+// files, and only when the caller did not inject an explicit env. A caller that
+// passes its own env object (embedded callers, tests) is authoritative and
+// hermetic — ambient discovery is suppressed so a developer's real key never
+// bleeds into a test run.
+
+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;
+}
+
+// The persona prompt is the specialist's system context. It lives in
+// specialists/prompts/cx-<role>.md; absent that file, a minimal role-named system
+// prompt keeps the backend functional rather than failing on a missing persona.
+
+function loadPersona(role) {
+  const slug = String(role || '').replace(/^cx-/, '');
+  const file = join(PROMPTS_DIR, `cx-${slug}.md`);
+  try {
+    if (existsSync(file)) return readFileSync(file, 'utf8');
+  } catch { /* unreadable persona falls back to the minimal prompt */ }
+  return `You are the ${slug} specialist. Execute your part of the request within your role and return your result directly.`;
+}
+
+function buildUserPrompt({ task, run }) {
+  const summary = run?.request?.summary || '';
+  const reason = task?.reason ? `\n\nWhy you were dispatched: ${task.reason}` : '';
+  const handoff = task?.handoffContract ? `\nHandoff contract: ${task.handoffContract}` : '';
+  return `Request: ${summary}${reason}${handoff}\n\nDo your part of this request as the ${String(task?.role || '').replace(/^cx-/, '')} specialist. Return your result directly.`;
+}
+
+async function bodyExcerpt(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return '';
+  }
+}
+
+async function callAnthropic({ model, apiKey, system, user, 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,
+      system,
+      messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `Anthropic specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  return (data.content || []).filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+}
+
+async function callOpenRouter({ model, apiKey, system, user, 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: 'system', content: system }, { role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenRouter specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || '';
+}
+
+/**
+ * Execute one specialist task via the configured provider/model.
+ *
+ * @param {object} opts
+ * @param {object} opts.task            the run task (carries role, reason, handoffContract)
+ * @param {object} opts.run             the run (carries request summary)
+ * @param {string} opts.model           resolved provider model id
+ * @param {string} [opts.provider]      resolved provider id (selects the API)
+ * @param {Record<string,string>} [opts.env]
+ * @param {Function} [opts.fetchImpl]   injectable fetch (for tests)
+ * @returns {Promise<{output:string, model:string, provider:string, characters:number}>}
+ */
+export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
+  if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
+
+  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'} specialist execution.`, `Set ${keyVar}, or set orchestration.workerBackend to "inline".`);
+  }
+
+  const system = loadPersona(task?.role);
+  const user = buildUserPrompt({ task, run });
+  const output = anthropic
+    ? await callAnthropic({ model, apiKey, system, user, fetchImpl })
+    : await callOpenRouter({ model, apiKey, system, user, fetchImpl });
+
+  const text = output || '';
+  return {
+    output: text,
+    model,
+    provider: anthropic ? 'anthropic' : 'openrouter',
+    characters: text.length,
+  };
+}

package/lib/parity.mjs

@@ -30,6 +30,38 @@ import { fileURLToPath } from 'node:url';
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(MODULE_DIR, '..');
 
+// VS Code and Cursor user settings are JSONC: line/block comments and trailing
+// commas are valid and common. Strict JSON.parse rejects them, producing a
+// false "unreadable" parity failure on a perfectly valid editor config. This
+// strips comments string-aware (so `//` inside a "https://…" value survives)
+// and drops trailing commas before parsing.
+
+function parseJsonc(text) {
+  let out = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; out += ch; continue; }
+    if (ch === '/' && next === '/') { while (i < text.length && text[i] !== '\n') i += 1; out += '\n'; continue; }
+    if (ch === '/' && next === '*') { i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1; i += 1; continue; }
+    out += ch;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function readJsoncFile(file) {
+  return parseJsonc(fs.readFileSync(file, 'utf8'));
+}
+
 function loadRegistry(rootDir = ROOT_DIR) {
   const file = path.join(rootDir, 'specialists', 'registry.json');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -130,7 +162,7 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
@@ -183,7 +215,7 @@ function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
   const actualSet = new Set();
   for (const settingsPath of paths) {
     try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const settings = readJsoncFile(settingsPath);
       for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
     } catch (err) {
       return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
@@ -208,7 +240,7 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   if (!fs.existsSync(file)) return { surface: 'cursor', kind: 'mcps', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
   }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "type": "module",
+  "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
     "construct": "bin/construct"