@geraldmaron/construct 1.4.1 → 1.4.2

package/lib/mcp-platform-config.mjs

@@ -37,12 +37,6 @@ function isUnwritableEnvValue(value) {
   return typeof value !== "string" || value.includes("__") || value.startsWith("op://");
 }
 
-function stripUnresolvedValues(input) {
-  return Object.fromEntries(
-    Object.entries(input).filter(([, value]) => !isUnwritableEnvValue(value)),
-  );
-}
-
 function resolveArgs(args, resolvedValues) {
   return (args ?? []).map((arg) =>
     typeof arg === "string" ? resolveTemplateString(arg, resolvedValues) : arg,
@@ -61,16 +55,31 @@ const SECRET_REF = {
   opencode: (name) => `{env:${name}}`,
 };
 
-// Local/stdio MCP env is materialized as resolved values rather than host env-ref
-// forms. The SECRET_REF syntaxes above are verified for the remote `headers` field
-// only; whether Claude / VS Code / OpenCode expand a `${VAR}`-style reference inside
-// a stdio `env` block is unconfirmed, so the value-to-reference flip is deferred. The
-// secret is still kept off disk by the child inheriting resolved env from the parent
-// (config.env -> loadConstructEnv -> process.env); `stripUnresolvedValues` guarantees
-// no unresolved template or op:// reference is persisted here.
-
-function buildLocalEnvironment(mcpDef, resolvedValues) {
-  return stripUnresolvedValues(resolveTemplateObject(mcpDef.env ?? {}, resolvedValues));
+// A stdio MCP env value that is a whole-value secret template (`__NAME__` as the
+// entire string) is a credential carrier: emit the host's env-reference form so the
+// live value never lands on disk, exactly as the remote `headers` path does. Claude
+// Code (`${VAR}`), VS Code (`${env:VAR}`), and OpenCode (`{env:VAR}`) each expand
+// their reference syntax inside a stdio env block, and the child still inherits the
+// resolved env from the parent (config.env -> loadConstructEnv -> process.env) as a
+// backstop. A composed value (a URL with an embedded port template, a plain literal)
+// is not a secret and is materialized so the child receives the concrete string;
+// op:// references and unresolved embedded templates are stripped, never persisted.
+
+const WHOLE_SECRET_TEMPLATE = /^__([A-Z0-9_]+)__$/;
+
+function buildLocalEnvironment(mcpDef, resolvedValues, secretRef) {
+  const source = mcpDef.env ?? {};
+  const out = {};
+  for (const [key, raw] of Object.entries(source)) {
+    const whole = typeof raw === "string" ? raw.match(WHOLE_SECRET_TEMPLATE) : null;
+    if (whole) {
+      out[key] = secretRef(whole[1]);
+      continue;
+    }
+    const materialized = typeof raw === "string" ? resolveTemplateString(raw, resolvedValues) : raw;
+    if (!isUnwritableEnvValue(materialized)) out[key] = materialized;
+  }
+  return out;
 }
 
 function buildRemoteHeaders(mcpDef, secretRef) {
@@ -106,7 +115,7 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}, { host = "c
     };
   }
 
-  const env = buildLocalEnvironment(mcpDef, values);
+  const env = buildLocalEnvironment(mcpDef, values, secretRef);
   return {
     command: mcpDef.command,
     args: resolveArgs(mcpDef.args, values),
@@ -137,7 +146,7 @@ export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}, { auth =
     };
   }
 
-  const environment = buildLocalEnvironment(mcpDef, runtimeValues);
+  const environment = buildLocalEnvironment(mcpDef, runtimeValues, SECRET_REF.opencode);
   return {
     id: openCodeId,
     entry: {

package/lib/oracle/daemon-entry.mjs

@@ -7,8 +7,14 @@
 
 import { runOracleDaemon } from './index.mjs';
 import { defaultRootDir } from './actions.mjs';
+import { enableSecretAuditTrail } from '../providers/secret-audit-wiring.mjs';
 
 const rootDir = process.env.CONSTRUCT_ORACLE_ROOT || defaultRootDir();
 const projectDir = process.env.CONSTRUCT_ORACLE_PROJECT || process.cwd();
 
+// A long-lived daemon in its own process: wire the audit sink at the entry so any
+// credential resolution the tick performs is recorded on the shared trail rather than
+// escaping it, matching the CLI entrypoint's own wiring.
+enableSecretAuditTrail();
+
 await runOracleDaemon({ rootDir, projectDir });

package/lib/orchestration/runtime.mjs

@@ -30,6 +30,8 @@
  */
 
 import { randomBytes } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 
 import { routeRequest } from '../orchestration-policy.mjs';
 import { resolveExecution } from '../embedded-contract/execution.mjs';
@@ -39,6 +41,7 @@ import { CHAIN_OF_THOUGHT_MODES } from '../config/schema.mjs';
 import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
 import { resolveRunStore } from './store.mjs';
 import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
+import { roleHoldsWebCapability } from './web-capability.mjs';
 import { emitRunEvent, isCancelRequested, clearCancel } from './events.mjs';
 
 export const WORKER_BACKENDS = WORKER_BACKEND_SET;
@@ -213,6 +216,9 @@ function prepareTaskInline(task) {
   task.executor = 'inline:prepared';
   task.status = 'prepared';
   task.finishedAt = new Date().toISOString();
+  // A prepared web-capable task reached no web: mark it so a host never infers live
+  // web access from a task that only planned (ADR-0050).
+  if (roleHoldsWebCapability(task.role)) task.webCapability = 'prepare-only';
 }
 
 // The provider backend executes one task against the configured model. A failed
@@ -232,10 +238,19 @@ async function executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought)
     task.status = 'done';
     task.finishedAt = new Date().toISOString();
 
+    // Web-capable execution records which grant mode reached (or did not reach) the web
+    // and the F08-governed evidence gathered, so a host never has to infer it (ADR-0050).
+    if (result.webCapability) {
+      task.webCapability = result.webCapability;
+      task.webEvidence = result.webEvidence || [];
+      task.webCalls = result.webCalls || 0;
+      task.webSearchRequests = result.webSearchRequests || 0;
+    }
+
     // `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 || '' };
+    return { ok: true, reasoning: result.reasoning || '', webCapability: result.webCapability || null };
   } catch (err) {
     task.executor = `provider:error`;
     task.error = { code: err.code || 'PROVIDER_EXECUTION_FAILED', message: err.message };
@@ -264,53 +279,77 @@ export async function executeRun(cwd, runId, { env = process.env, workerBackend
     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();
-  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, workerBackend: backend } });
-    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: 'running' });
-
-    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);
+  const runFilePath = join(cwd, '.cx', 'runtime', 'orchestration', 'runs', `${runId}.json`);
+
+  try {
+    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();
+    await store.saveRun(run);
+    emitRunEvent(runId, { type: 'running', status: 'running', workerBackend: backend });
+
+    let anyFailed = false;
+    let cancelled = false;
+    let webUnavailable = 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, workerBackend: backend } });
+      emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: 'running' });
+
+      let taskReasoning = '';
+      if (backend === PROVIDER) {
+        const res = await executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought);
+        if (!res.ok) anyFailed = true;
+        if (res.webCapability === 'unavailable') webUnavailable = 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();
+      await store.saveRun(run);
     }
 
-    // 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;
+    run.status = cancelled ? 'cancelled' : (anyFailed ? 'completed-with-failures' : 'completed');
+    // A web-capable task that reached no web path degrades the run so a host surfaces the
+    // capability gap rather than treating an insufficient-evidence answer as complete.
+    if (webUnavailable) {
+      run.degraded = true;
+      run.degradationReason = 'capability-unavailable';
     }
-    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();
     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;
+  } catch (err) {
+    run.status = 'error';
+    run.error = { code: err.code || 'RUN_EXECUTE_FAILED', message: err.message };
+    run.updatedAt = new Date().toISOString();
+    // Direct (non-atomic) write to the existing run file: the file was created by
+    // planRun so the inode exists; overwriting an existing file succeeds even on a
+    // read-only directory (only creating new files requires write permission on the
+    // directory itself). This persists the terminal failure durably so
+    // getRun/getRuns surfaces the error status to doctor and orchestration_status.
+    try { writeFileSync(runFilePath, `${JSON.stringify(run, null, 2)}\n`); } catch { /* best-effort */ }
+    emitRunEvent(runId, { type: 'error', status: 'error', error: run.error });
+    throw err;
   }
-
-  run.status = cancelled ? 'cancelled' : (anyFailed ? 'completed-with-failures' : 'completed');
-  run.updatedAt = new Date().toISOString();
-  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;
 }
 
 /**

package/lib/orchestration/web-capability.mjs

@@ -0,0 +1,59 @@
+/**
+ * lib/orchestration/web-capability.mjs — resolve a web-capable specialist's live-web grant (ADR-0050).
+ *
+ * roleHoldsWebCapability reads the specialist's own declared tools (claudeTools carrying
+ * WebSearch/WebFetch) so the web role is derived from the capability map, never a hardcoded
+ * string. resolveWebCapability returns a typed WebGrant in strict priority so the same
+ * contract governs the local worker, the remote service, and inline mode:
+ *   - governed        (WEB_SEARCH_URL set): the worker runs a client tool-use loop over
+ *                      Construct's own webSearch(), so F08 grading is preserved by construction.
+ *   - provider-native (no WEB_SEARCH_URL): Anthropic web_search_20250305 or OpenRouter
+ *                      openrouter:web_search server tool; every citation is re-graded through
+ *                      governWebResults so trust:'untrusted' + Admiralty hold identically.
+ *   - host-delegated  (explicit opt-in): a tool-capable host executes and returns already-F08
+ *                      evidence, re-validated fail-closed on ingress.
+ *   - unavailable     (nothing resolves): a typed capability-unavailable that forces an honest
+ *                      refusal per rules/common/no-fabrication.md — never a fabricated citation.
+ */
+
+import { getSpecialist } from '../registry/loader.mjs';
+
+const DEFAULT_MAX_USES = 5;
+const DEFAULT_MAX_RESULTS = 5;
+
+// A specialist is web-execution-capable only when it explicitly declares liveWebAccess.
+// claudeTools carries WebSearch/WebFetch on most specialists (the broad Claude-host grant),
+// so it is NOT the signal here — the orchestrator routes live-web work to the one role that
+// declares the capability (the researcher), keeping the worker web tool least-privilege.
+export function roleHoldsWebCapability(role, opts = {}) {
+  try {
+    const spec = getSpecialist(role, opts.rootDir ? { rootDir: opts.rootDir } : {});
+    return spec?.liveWebAccess === true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveWebCapability({ family, env = process.env } = {}) {
+  if (env.WEB_SEARCH_URL) {
+    return { mode: 'governed' };
+  }
+  if (family === 'anthropic') {
+    const maxUses = Number(env.CONSTRUCT_WORKER_WEB_MAX_USES) || DEFAULT_MAX_USES;
+    return { mode: 'provider-native', providerTool: 'anthropic', toolType: 'web_search_20250305', maxUses };
+  }
+  if (family === 'openrouter') {
+    const maxResults = Number(env.CONSTRUCT_WORKER_WEB_MAX_RESULTS) || DEFAULT_MAX_RESULTS;
+    return {
+      mode: 'provider-native',
+      providerTool: 'openrouter',
+      toolSpec: { type: 'openrouter:web_search', parameters: { engine: 'auto', max_results: maxResults } },
+    };
+  }
+  // openai / github-copilot have no native web tool wired here; delegate only when
+  // explicitly opted in, otherwise the honesty guard fires.
+  if (env.CONSTRUCT_ORCHESTRATION_WEB_DELEGATE === '1') {
+    return { mode: 'host-delegated' };
+  }
+  return { mode: 'unavailable', reason: 'capability-unavailable' };
+}