@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/orchestration/runtime.mjs

@@ -1,25 +1,32 @@
 /**
- * lib/orchestration/runtime.mjs — Construct-owned local orchestration runtime (Mode-A).
+ * 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 is the
- * Mode-A (zero-dependency, single-process, filesystem-backed) slice of that
- * runtime: it 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 (run-store), and emits lifecycle traces.
+ * 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.
  *
- * Honesty boundary (ADR-0020, extending ADR-0019): the Mode-A worker backend is
- * `inline` — it OWNS planning, sequencing, handoff state, persistence, and
- * observability, and PREPARES each specialist task (role, reason, handoff
- * contract) for a downstream executor. It does NOT itself perform specialist LLM
- * reasoning; a provider-backed worker backend is a separate, later backend. 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 rather than implying orchestration.
+ * 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';
@@ -27,13 +34,19 @@ 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 { CHAIN_OF_THOUGHT_MODES } from '../config/schema.mjs';
 import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
-import { saveRun, loadRun, listRuns } from './run-store.mjs';
+import { resolveRunStore } from './store.mjs';
+import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
+import { emitRunEvent, isCancelRequested, clearCancel } from './events.mjs';
 
-export const WORKER_BACKENDS = ['inline'];
-export const DEFAULT_WORKER_BACKEND = 'inline';
+export const WORKER_BACKENDS = WORKER_BACKEND_SET;
+export const DEFAULT_WORKER_BACKEND = INLINE;
+export const CHAIN_OF_THOUGHT = CHAIN_OF_THOUGHT_MODES;
+export const DEFAULT_CHAIN_OF_THOUGHT = 'hidden';
 
-const RUNTIME_SEMANTICS = 'Mode-A inline 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.';
+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')}`;
@@ -87,25 +100,58 @@ function buildTasks(route) {
     handoffContract: handoffByProducer.get(role.replace(/^cx-/, '')) || null,
     status: 'queued',
     executor: null,
+    output: null,
+    reasoning: 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;
+}
+
+// Chain-of-thought disclosure is a deployment concern (ADR-0030): an explicit
+// option wins, then the run's recorded mode, then config
+// (orchestration.chainOfThought), then the hidden default. An unknown value
+// falls back to hidden — specialist reasoning is never surfaced by guess.
+
+function resolveChainOfThought({ explicit, run, config }) {
+  const candidate = explicit || run?.chainOfThought || config?.orchestration?.chainOfThought || DEFAULT_CHAIN_OF_THOUGHT;
+  return CHAIN_OF_THOUGHT.includes(candidate) ? candidate : DEFAULT_CHAIN_OF_THOUGHT;
+}
+
+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 {object} the persisted run
+ * @returns {Promise<object>} the persisted run
  */
-export function planRun(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+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 },
@@ -115,6 +161,8 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
   const traceId = newTraceId();
   const runId = newRunId();
   const now = new Date().toISOString();
+  const workerBackend = resolveWorkerBackend({ config });
+  const chainOfThought = resolveChainOfThought({ 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
@@ -129,7 +177,8 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
     updatedAt: now,
     request: { summary: truncate(text, 200), workflowType, requestedStrategy },
     hostRole: resolveHostRole(host),
-    workerBackend: DEFAULT_WORKER_BACKEND,
+    workerBackend,
+    chainOfThought,
     execution: pickExecution(execData),
     plan: {
       intent: route.intent,
@@ -140,69 +189,153 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
     },
     tasks,
     status: 'planned',
-    warnings: execData.warnings || [],
+    warnings: [...(execData.warnings || []), ...storeWarnings],
     semantics: RUNTIME_SEMANTICS,
     executionSemantics: execData.semantics,
   };
 
-  saveRun(cwd, run);
+  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 },
   });
+  emitRunEvent(runId, { type: 'planned', status: 'planned', executionMode: run.execution.executionMode, taskCount: tasks.length });
   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, chainOfThought) {
+  try {
+    const result = await runTaskViaProvider({
+      task, run,
+      model: run.execution?.selectedModel,
+      provider: run.execution?.selectedProvider,
+      env, fetchImpl, chainOfThought,
+    });
+    task.output = result.output;
+    task.executor = `provider:${result.provider}:${result.model}`;
+    task.status = 'done';
+    task.finishedAt = new Date().toISOString();
+
+    // `surface` attaches reasoning to the task so every display surface renders
+    // it; `telemetry_only` keeps it off the task (recorded only in the trace).
+    if (chainOfThought === 'surface' && result.reasoning) task.reasoning = result.reasoning;
+    return { ok: true, reasoning: result.reasoning || '' };
+  } 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 { ok: false, reasoning: '' };
+  }
+}
+
 /**
- * Execute a planned run through the inline (Mode-A) worker backend: advance each
- * task queued → running → prepared, persisting after each transition so the run
- * is resumable and observable. The inline backend prepares tasks; it does not
- * perform specialist LLM reasoning.
+ * 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 }
- * @returns {object} the completed run
+ * @param {object} [opts]   { env, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the completed run
  */
-export function executeRun(cwd, runId, { env = process.env } = {}) {
-  const run = loadRun(cwd, runId);
+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 });
+  const chainOfThought = resolveChainOfThought({ run, config });
+  run.workerBackend = backend;
+  run.chainOfThought = chainOfThought;
   run.status = 'running';
   run.updatedAt = new Date().toISOString();
-  saveRun(cwd, run);
+  await store.saveRun(run);
+  emitRunEvent(runId, { type: 'running', status: 'running', workerBackend: backend });
 
+  let anyFailed = false;
+  let cancelled = false;
   for (const task of run.tasks) {
+    if (isCancelRequested(runId)) { cancelled = true; break; }
     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 } });
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.started', role: task.role, taskId: task.id, metadata: { runId, workerBackend: backend } });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: 'running' });
 
-    task.executor = 'inline:prepared';
-    task.status = 'prepared';
-    task.finishedAt = new Date().toISOString();
-    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: { runId, status: 'prepared' } });
+    let taskReasoning = '';
+    if (backend === PROVIDER) {
+      const res = await executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought);
+      if (!res.ok) anyFailed = true;
+      taskReasoning = res.reasoning;
+    } else {
+      prepareTaskInline(task);
+    }
 
+    // telemetry_only records reasoning to the trace without ever surfacing it to
+    // a display; surface keeps it off the trace (it rides on task.reasoning).
+    const completedMeta = { runId, status: task.status };
+    if (chainOfThought === 'telemetry_only' && taskReasoning) {
+      completedMeta.reasoning = taskReasoning;
+      completedMeta.reasoningChars = taskReasoning.length;
+    }
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: completedMeta });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: task.status, executor: task.executor, ...(task.reasoning ? { reasoning: task.reasoning } : {}), ...(task.error ? { error: task.error } : {}) });
     run.updatedAt = new Date().toISOString();
-    saveRun(cwd, run);
+    await store.saveRun(run);
   }
 
-  run.status = 'completed';
+  run.status = cancelled ? 'cancelled' : (anyFailed ? 'completed-with-failures' : 'completed');
   run.updatedAt = new Date().toISOString();
-  saveRun(cwd, run);
+  await store.saveRun(run);
+  clearCancel(runId);
   emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
+  emitRunEvent(runId, { type: 'completed', status: run.status });
   return run;
 }
 
 /**
  * Plan and execute in one call (the common `orchestrate run` path).
  */
-export function runOrchestration(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
-  const planned = planRun(request, { env, cwd });
-  return executeRun(cwd, planned.runId, { env });
+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 });
+}
+
+/**
+ * Start a run for a thin client: plan + persist synchronously, then execute in
+ * the BACKGROUND (not awaited) so the caller gets a runId immediately and tracks
+ * progress via the event stream / run store. Execution failures are caught and
+ * surfaced as a terminal `error` run event rather than an unhandled rejection.
+ *
+ * @param {object} request
+ * @param {object} [opts]   { env, cwd, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the planned run (status `planned`)
+ */
+export async function startRun(request = {}, { env = process.env, cwd = process.cwd(), workerBackend = null, fetchImpl } = {}) {
+  const planned = await planRun(request, { env, cwd });
+  Promise.resolve()
+    .then(() => executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl }))
+    .catch((err) => {
+      emitRunEvent(planned.runId, { type: 'error', status: 'error', error: { code: err.code || 'RUN_FAILED', message: err.message } });
+    });
+  return planned;
 }
 
 /**
@@ -219,22 +352,27 @@ export function hostAdapterMetadata(run) {
     executionMode: e.executionMode,
     constructCapabilitiesActive: e.constructCapabilitiesActive,
     workerBackend: run.workerBackend,
+    chainOfThought: run.chainOfThought ?? null,
     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 })),
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null })),
     warnings: run.warnings || [],
     semantics: run.semantics,
     executionSemantics: run.executionSemantics,
   };
 }
 
-export function getRun(cwd, runId) {
-  return loadRun(cwd, runId);
+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 function getRuns(cwd, opts) {
-  return listRuns(cwd, opts);
+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 };
+}