@geraldmaron/construct 1.0.0

package/lib/telemetry/backends/langfuse.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/telemetry/backends/langfuse.mjs — Langfuse trace backend adapter.
+ *
+ * Reads LANGFUSE_BASEURL, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY from env.
+ * Implements the TraceBackend interface: listTraces(teamId, windowMs) → Trace[].
+ */
+
+export const name = 'langfuse';
+
+function baseHeaders() {
+  const key = process.env.LANGFUSE_PUBLIC_KEY;
+  const secret = process.env.LANGFUSE_SECRET_KEY;
+  if (!key || !secret) throw new Error('LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY must be set.');
+  return {
+    Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`,
+    'Content-Type': 'application/json',
+  };
+}
+
+function baseUrl() {
+  return (process.env.LANGFUSE_BASEURL ?? 'https://cloud.langfuse.com').replace(/\/$/, '');
+}
+
+export async function isAvailable() {
+  return Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY);
+}
+
+/**
+ * Fetch traces associated with a teamId within a time window.
+ * Returns an array of normalized Trace objects.
+ *
+ * @param {string} teamId - The overlay/team ID to filter by.
+ * @param {number} windowMs - Lookback window in milliseconds.
+ * @returns {Promise<Trace[]>}
+ */
+export async function listTraces(teamId, windowMs) {
+  const since = new Date(Date.now() - windowMs).toISOString();
+  const url = `${baseUrl()}/api/public/traces?tags=${encodeURIComponent(teamId)}&fromTimestamp=${since}&limit=100`;
+
+  const resp = await fetch(url, { headers: baseHeaders() });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Langfuse API error ${resp.status}: ${body}`);
+  }
+  const json = await resp.json();
+
+  return (json.data ?? []).map((t) => ({
+    id: t.id,
+    teamId,
+    agentName: t.metadata?.agentName ?? t.name ?? 'unknown',
+    status: t.metadata?.status ?? 'unknown',
+    latencyMs: t.latency != null ? Math.round(t.latency * 1000) : null, // Langfuse returns seconds
+    qualityScore: t.scores?.find((s) => s.name === 'quality')?.value ?? null,
+    createdAt: t.timestamp,
+    blockers: t.metadata?.blockers ?? [],
+    handoffs: t.metadata?.handoffs ?? 0,
+  }));
+}

package/lib/telemetry/backends/noop.mjs

@@ -0,0 +1,16 @@
+/**
+ * lib/telemetry/backends/noop.mjs — No-op trace backend for when no backend is configured.
+ *
+ * Returns empty results for all queries. Useful for local debug logging and
+ * environments where telemetry is optional.
+ */
+
+export const name = 'noop';
+
+export async function listTraces(_teamId, _windowMs) {
+  return [];
+}
+
+export async function isAvailable() {
+  return true;
+}

package/lib/telemetry/langfuse-ingest.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/telemetry/langfuse-ingest.mjs — Langfuse batch ingestion client.
+ *
+ * POSTs observations to /api/public/ingestion in batches. Silent no-op when
+ * LANGFUSE_PUBLIC_KEY/SECRET_KEY are missing. Never throws from the hot path.
+ */
+import { randomUUID } from "node:crypto";
+
+const DEFAULT_FLUSH_INTERVAL_MS = 500;
+const DEFAULT_MAX_BATCH = 50;
+const MAX_PAYLOAD_CHARS = 16_000;
+
+function truncate(value) {
+  if (value == null) return value;
+  if (typeof value === "string") {
+    return value.length > MAX_PAYLOAD_CHARS
+      ? `${value.slice(0, MAX_PAYLOAD_CHARS)}…[truncated ${value.length - MAX_PAYLOAD_CHARS} chars]`
+      : value;
+  }
+  try {
+    const json = JSON.stringify(value);
+    if (json.length <= MAX_PAYLOAD_CHARS) return value;
+    return { _truncated: true, originalBytes: json.length, preview: json.slice(0, MAX_PAYLOAD_CHARS) };
+  } catch {
+    return value;
+  }
+}
+
+export function createIngestClient({
+  baseUrl = (process.env.LANGFUSE_BASEURL ?? "https://cloud.langfuse.com").replace(/\/$/, ""),
+  publicKey = process.env.LANGFUSE_PUBLIC_KEY,
+  secretKey = process.env.LANGFUSE_SECRET_KEY,
+  flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS,
+  maxBatch = DEFAULT_MAX_BATCH,
+  onError = () => {},
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const available = Boolean(publicKey && secretKey && fetchImpl);
+  const queue = [];
+  let flushTimer = null;
+  let inflight = Promise.resolve();
+
+  const authHeader = available
+    ? `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}`
+    : "";
+
+  function scheduleFlush() {
+    if (!available || flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flushBatch();
+    }, flushIntervalMs);
+    if (typeof flushTimer.unref === "function") flushTimer.unref();
+  }
+
+  async function flushBatch() {
+    if (!available || queue.length === 0) return;
+    const batch = queue.splice(0, maxBatch);
+    const payload = JSON.stringify({ batch });
+    const prev = inflight;
+    inflight = (async () => {
+      try { await prev; } catch { /* ignore prior */ }
+      try {
+        const res = await fetchImpl(`${baseUrl}/api/public/ingestion`, {
+          method: "POST",
+          headers: { Authorization: authHeader, "Content-Type": "application/json" },
+          body: payload,
+        });
+        if (!res.ok && res.status !== 207) {
+          let detail = "";
+          try { detail = (await res.text()).slice(0, 500); } catch { /* ignore */ }
+          onError(new Error(`langfuse ingest ${res.status}: ${detail}`));
+        }
+      } catch (err) {
+        onError(err);
+      }
+    })();
+    if (queue.length >= maxBatch) scheduleFlush();
+  }
+
+  function push(type, body) {
+    if (!available || !body) return;
+    const cleaned = {
+      ...body,
+      input: body.input !== undefined ? truncate(body.input) : undefined,
+      output: body.output !== undefined ? truncate(body.output) : undefined,
+    };
+    queue.push({ id: randomUUID(), type, timestamp: new Date().toISOString(), body: cleaned });
+    if (queue.length >= maxBatch) { void flushBatch(); return; }
+    scheduleFlush();
+  }
+
+  return {
+    available,
+    trace: (body) => push("trace-create", body),
+    generation: (body) => push("generation-create", body),
+    generationUpdate: (body) => push("generation-update", body),
+    span: (body) => push("span-create", body),
+    spanUpdate: (body) => push("span-update", body),
+    event: (body) => push("event-create", body),
+    async flush() {
+      if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+      while (queue.length > 0) await flushBatch();
+      await inflight;
+    },
+    queueSize: () => queue.length,
+  };
+}

package/lib/telemetry/langfuse-model-sync.mjs

@@ -0,0 +1,270 @@
+/**
+ * lib/telemetry/langfuse-model-sync.mjs — Sync live model pricing into Langfuse.
+ *
+ * Fetches OpenRouter's public model list for live pricing, merges with a static
+ * Anthropic table (no machine-readable public pricing API), and upserts all
+ * entries into Langfuse's custom model registry so that traces show real costs.
+ *
+ * Designed to be called once at plugin init; subsequent calls within the same
+ * process are skipped via a module-level guard to avoid hammering the APIs.
+ */
+
+const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+
+// Static Anthropic pricing (USD per token, as of 2026-04).
+// No machine-readable public pricing endpoint — update on model price changes.
+const ANTHROPIC_MODELS = [
+  {
+    modelName: "claude-opus-4-7",
+    matchPattern: "(?i)^(anthropic/)?claude-opus-4-7$",
+    inputPrice: 15 / 1_000_000,
+    outputPrice: 75 / 1_000_000,
+  },
+  {
+    modelName: "claude-opus-4-5",
+    matchPattern: "(?i)^(anthropic/)?claude-opus-4-5$",
+    inputPrice: 15 / 1_000_000,
+    outputPrice: 75 / 1_000_000,
+  },
+  {
+    modelName: "claude-sonnet-4-6",
+    matchPattern: "(?i)^(anthropic/)?claude-sonnet-4-6$",
+    inputPrice: 3 / 1_000_000,
+    outputPrice: 15 / 1_000_000,
+  },
+  {
+    modelName: "claude-sonnet-4-5",
+    matchPattern: "(?i)^(anthropic/)?claude-sonnet-4-5$",
+    inputPrice: 3 / 1_000_000,
+    outputPrice: 15 / 1_000_000,
+  },
+  {
+    modelName: "claude-haiku-4-5",
+    matchPattern: "(?i)^(anthropic/)?claude-haiku-4-5(-\\d+)?$",
+    inputPrice: 0.8 / 1_000_000,
+    outputPrice: 4 / 1_000_000,
+  },
+];
+
+// GitHub Copilot uses a per-request billing model, not per-token.
+// Register at $0 so Langfuse records usage without phantom costs.
+const GITHUB_COPILOT_MODELS = [
+  { modelName: "github-copilot/gpt-5.4", matchPattern: "(?i)^(github-copilot/)?gpt-5\\.4$" },
+  { modelName: "github-copilot/gpt-4.1", matchPattern: "(?i)^(github-copilot/)?gpt-4\\.1$" },
+  { modelName: "github-copilot/claude-sonnet-4-5", matchPattern: "(?i)^github-copilot/claude-sonnet" },
+  { modelName: "github-copilot/gemini-2.5-pro", matchPattern: "(?i)^github-copilot/gemini" },
+  { modelName: "github-copilot/o4-mini", matchPattern: "(?i)^github-copilot/o4" },
+].map((m) => ({ ...m, inputPrice: 0, outputPrice: 0 }));
+
+let syncDone = false;
+let cachedPricingCatalog = buildPricingCatalog();
+
+function normalizeModelKey(modelName = "") {
+  return String(modelName ?? "").trim().toLowerCase();
+}
+
+function indexPricingEntry(map, model) {
+  if (!model?.modelName) return;
+  const key = normalizeModelKey(model.modelName);
+  const entry = {
+    modelName: model.modelName,
+    inputPrice: Number(model.inputPrice) || 0,
+    outputPrice: Number(model.outputPrice) || 0,
+    source: model.source || "catalog",
+  };
+  map.set(key, entry);
+  if (key.startsWith("anthropic/")) map.set(key.replace(/^anthropic\//, ""), entry);
+  if (key.startsWith("github-copilot/")) map.set(key.replace(/^github-copilot\//, ""), entry);
+  if (key.startsWith("openrouter/")) map.set(key.replace(/^openrouter\//, ""), entry);
+}
+
+export function buildPricingCatalog(openRouterModels = []) {
+  const map = new Map();
+  for (const model of [...ANTHROPIC_MODELS, ...GITHUB_COPILOT_MODELS]) {
+    indexPricingEntry(map, { ...model, source: "static" });
+  }
+  for (const model of openRouterModels) {
+    indexPricingEntry(map, { ...model, source: "openrouter" });
+  }
+  return map;
+}
+
+export function resolveModelPricing(modelName, catalog = cachedPricingCatalog) {
+  const key = normalizeModelKey(modelName);
+  if (!key) return null;
+  return catalog.get(key) || null;
+}
+
+export function estimateUsageCost(modelName, usage = {}, catalog = cachedPricingCatalog) {
+  const pricing = resolveModelPricing(modelName, catalog);
+  if (!pricing) return { costUsd: 0, costSource: "unavailable", modelName: modelName || null };
+
+  const inputTokens = Number(usage.inputTokens ?? 0);
+  const outputTokens = Number(usage.outputTokens ?? 0);
+  const reasoningTokens = Number(usage.reasoningTokens ?? 0);
+  const billableOutputTokens = outputTokens + reasoningTokens;
+  const inputCost = inputTokens * pricing.inputPrice;
+  const outputCost = billableOutputTokens * pricing.outputPrice;
+  const costUsd = inputCost + outputCost;
+
+  return {
+    costUsd,
+    costSource: `estimated:${pricing.source}`,
+    modelName: pricing.modelName,
+    pricing,
+    breakdown: {
+      inputCostUsd: inputCost,
+      outputCostUsd: outputCost,
+      billableInputTokens: inputTokens,
+      billableOutputTokens,
+    },
+  };
+}
+
+function buildAuthHeader(publicKey, secretKey) {
+  return `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}`;
+}
+
+async function fetchOpenRouterModels(fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl(OPENROUTER_MODELS_URL, {
+      headers: { "User-Agent": "construct-telemetry/1.0" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return [];
+    const { data } = await res.json();
+    if (!Array.isArray(data)) return [];
+    return data
+      .filter((m) => m?.id && m?.pricing)
+      .map((m) => {
+        const inputPrice = parseFloat(m.pricing.prompt) || 0;
+        const outputPrice = parseFloat(m.pricing.completion) || 0;
+        // Escape dots and slashes in match pattern
+        const escaped = m.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return {
+          modelName: m.id,
+          matchPattern: `(?i)^${escaped}$`,
+          inputPrice,
+          outputPrice,
+        };
+      });
+  } catch {
+    return [];
+  }
+}
+
+async function listLangfuseModels(baseUrl, authHeader, fetchImpl) {
+  const all = [];
+  let page = 1;
+  try {
+    while (true) {
+      const res = await fetchImpl(`${baseUrl}/api/public/models?limit=100&page=${page}`, {
+        headers: { Authorization: authHeader },
+        signal: AbortSignal.timeout(8_000),
+      });
+      if (!res.ok) break;
+      const body = await res.json();
+      const items = Array.isArray(body?.data) ? body.data : [];
+      all.push(...items);
+      if (items.length < 100) break;
+      page++;
+    }
+  } catch { /* return what we have */ }
+  return all;
+}
+
+async function deleteLangfuseModel(baseUrl, authHeader, id, fetchImpl) {
+  try {
+    await fetchImpl(`${baseUrl}/api/public/models/${id}`, {
+      method: "DELETE",
+      headers: { Authorization: authHeader },
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch { /* best effort */ }
+}
+
+async function upsertLangfuseModel(baseUrl, authHeader, model, existing, fetchImpl) {
+  const match = existing.find((e) => e.modelName === model.modelName);
+  if (match) {
+    // Langfuse has no PATCH; delete then recreate if pricing changed.
+    const priceChanged =
+      Math.abs((match.inputPrice ?? 0) - model.inputPrice) > 1e-12 ||
+      Math.abs((match.outputPrice ?? 0) - model.outputPrice) > 1e-12;
+    if (!priceChanged) return "unchanged";
+    await deleteLangfuseModel(baseUrl, authHeader, match.id, fetchImpl);
+  }
+  const body = JSON.stringify({
+    modelName: model.modelName,
+    matchPattern: model.matchPattern,
+    unit: "TOKENS",
+    inputPrice: model.inputPrice,
+    outputPrice: model.outputPrice,
+    tokenizerId: model.modelName.includes("claude") ? "claude" : null,
+  });
+  try {
+    const res = await fetchImpl(`${baseUrl}/api/public/models`, {
+      method: "POST",
+      headers: { Authorization: authHeader, "Content-Type": "application/json" },
+      body,
+      signal: AbortSignal.timeout(5_000),
+    });
+    return res.ok ? "created" : "error";
+  } catch {
+    return "error";
+  }
+}
+
+/**
+ * Syncs model pricing into Langfuse. Safe to call multiple times — only runs once per process.
+ *
+ * @param {object} opts
+ * @param {string} opts.baseUrl — Langfuse base URL
+ * @param {string} opts.publicKey
+ * @param {string} opts.secretKey
+ * @param {Function} [opts.fetchImpl] — injectable fetch for tests
+ * @param {boolean} [opts.force] — bypass the once-per-process guard
+ * @returns {Promise<{synced: number, unchanged: number, errors: number}>}
+ */
+export async function syncModelPricing({
+  baseUrl = (process.env.LANGFUSE_BASEURL ?? "https://cloud.langfuse.com").replace(/\/$/, ""),
+  publicKey = process.env.LANGFUSE_PUBLIC_KEY,
+  secretKey = process.env.LANGFUSE_SECRET_KEY,
+  fetchImpl = globalThis.fetch,
+  force = false,
+} = {}) {
+  if (!force && syncDone) return { synced: 0, unchanged: 0, errors: 0 };
+  if (!publicKey || !secretKey || !fetchImpl) return { synced: 0, unchanged: 0, errors: 0 };
+
+  syncDone = true;
+
+  const authHeader = buildAuthHeader(publicKey, secretKey);
+
+  const [openRouterModels, existing] = await Promise.all([
+    fetchOpenRouterModels(fetchImpl),
+    listLangfuseModels(baseUrl, authHeader, fetchImpl),
+  ]);
+
+  const allModels = [...ANTHROPIC_MODELS, ...GITHUB_COPILOT_MODELS, ...openRouterModels];
+  cachedPricingCatalog = buildPricingCatalog(openRouterModels);
+
+  let synced = 0;
+  let unchanged = 0;
+  let errors = 0;
+
+  for (const model of allModels) {
+    const result = await upsertLangfuseModel(baseUrl, authHeader, model, existing, fetchImpl);
+    if (result === "created") synced++;
+    else if (result === "unchanged") unchanged++;
+    else errors++;
+  }
+
+  return { synced, unchanged, errors };
+}
+
+export function resetSyncGuard() {
+  syncDone = false;
+}
+
+export function resetPricingCatalog() {
+  cachedPricingCatalog = buildPricingCatalog();
+}

package/lib/telemetry/team-rollup.mjs

@@ -0,0 +1,143 @@
+/**
+ * lib/telemetry/team-rollup.mjs — Backend-agnostic team telemetry rollup.
+ *
+ * Groups agent traces by teamId (stamped by construct headhunt at overlay creation),
+ * computes per-team success rates, latency, handoff counts, and common blockers.
+ * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: langfuse).
+ * Called by 'construct team review'.
+ */
+
+import * as langfuseBackend from './backends/langfuse.mjs';
+import * as noopBackend from './backends/noop.mjs';
+
+const BACKENDS = {
+  langfuse: langfuseBackend,
+  noop: noopBackend,
+};
+
+const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+function resolveBackend() {
+  const name = process.env.CONSTRUCT_TRACE_BACKEND ?? 'langfuse';
+  const backend = BACKENDS[name];
+  if (!backend) throw new Error(`Unknown trace backend: ${name}. Available: ${Object.keys(BACKENDS).join(', ')}`);
+  return backend;
+}
+
+function median(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+function rollupByTeam(traces) {
+  const byTeam = {};
+  for (const trace of traces) {
+    const key = trace.teamId ?? 'unknown';
+    if (!byTeam[key]) byTeam[key] = { teamId: key, traces: [] };
+    byTeam[key].traces.push(trace);
+  }
+
+  return Object.values(byTeam).map(({ teamId, traces: tl }) => {
+    const total = tl.length;
+    const successes = tl.filter((t) => t.status === 'DONE').length;
+    const latencies = tl.map((t) => t.latencyMs).filter((v) => v != null);
+    const qualityScores = tl.map((t) => t.qualityScore).filter((v) => v != null);
+    const totalHandoffs = tl.reduce((acc, t) => acc + (t.handoffs ?? 0), 0);
+
+    const blockerCounts = {};
+    for (const t of tl) {
+      for (const b of (t.blockers ?? [])) {
+        blockerCounts[b] = (blockerCounts[b] ?? 0) + 1;
+      }
+    }
+    const topBlockers = Object.entries(blockerCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([label, count]) => ({ label, count }));
+
+    return {
+      teamId,
+      total,
+      successRate: total > 0 ? (successes / total) : null,
+      medianLatencyMs: median(latencies),
+      medianQualityScore: median(qualityScores),
+      totalHandoffs,
+      topBlockers,
+      agents: [...new Set(tl.map((t) => t.agentName))],
+    };
+  });
+}
+
+function formatRollup(rollups) {
+  const lines = [];
+  lines.push('Team Telemetry Rollup');
+  lines.push('═════════════════════');
+  lines.push('');
+
+  if (rollups.length === 0) {
+    lines.push('  No team traces found in the selected window.');
+    lines.push('  Run construct headhunt with --temp or a template, then tasks will generate traces.');
+    return lines.join('\n');
+  }
+
+  for (const r of rollups) {
+    const successPct = r.successRate != null ? `${(r.successRate * 100).toFixed(0)}%` : 'n/a';
+    const latency = r.medianLatencyMs != null ? `${(r.medianLatencyMs / 1000).toFixed(1)}s` : 'n/a';
+    const quality = r.medianQualityScore != null ? r.medianQualityScore.toFixed(2) : 'n/a';
+    lines.push(`  Team: ${r.teamId}`);
+    lines.push(`    Runs: ${r.total}  Success: ${successPct}  Median latency: ${latency}  Quality: ${quality}`);
+    lines.push(`    Handoffs: ${r.totalHandoffs}  Agents: ${r.agents.join(', ')}`);
+    if (r.topBlockers.length > 0) {
+      lines.push(`    Top blockers: ${r.topBlockers.map((b) => `${b.label} (${b.count})`).join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+export async function runTeamRollup({ windowMs = DEFAULT_WINDOW_MS, teamIds = [], silent = false } = {}) {
+  const backend = resolveBackend();
+
+  if (!(await backend.isAvailable())) {
+    if (!silent) {
+      process.stdout.write(`Trace backend '${backend.name}' is not configured — using noop.\n`);
+      process.stdout.write('Set CONSTRUCT_TRACE_BACKEND and required credentials to enable telemetry.\n');
+    }
+    return [];
+  }
+
+  const targets = teamIds.length > 0 ? teamIds : ['all'];
+  const allTraces = [];
+
+  for (const teamId of targets) {
+    const traces = await backend.listTraces(teamId === 'all' ? null : teamId, windowMs);
+    allTraces.push(...traces);
+  }
+
+  const rollups = rollupByTeam(allTraces);
+
+  if (!silent) {
+    process.stdout.write(formatRollup(rollups) + '\n');
+  }
+
+  return rollups;
+}
+
+export async function runTeamReviewCli(args = []) {
+  const windowArg = args.find((a) => a.startsWith('--window='))?.split('=')[1];
+  const windowMs = windowArg ? parseWindowArg(windowArg) : DEFAULT_WINDOW_MS;
+  const teamIds = args.filter((a) => !a.startsWith('--'));
+  await runTeamRollup({ windowMs, teamIds });
+}
+
+function parseWindowArg(value) {
+  const match = value.match(/^(\d+)(d|h|m)?$/);
+  if (!match) return DEFAULT_WINDOW_MS;
+  const n = parseInt(match[1], 10);
+  const unit = match[2] ?? 'd';
+  const multipliers = { d: 86_400_000, h: 3_600_000, m: 60_000 };
+  return n * (multipliers[unit] ?? multipliers.d);
+}

package/lib/toolkit-env.mjs

@@ -0,0 +1,30 @@
+/**
+ * lib/toolkit-env.mjs — Load `.env` from CX_TOOLKIT_DIR into process.env.
+ *
+ * Shared by OpenCode plugin and MCP server so Langfuse/OpenRouter creds
+ * reach every host that drives Construct.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function loadToolkitEnv(toolkitDir, env = process.env) {
+  if (!toolkitDir) return;
+  const envPath = join(toolkitDir, ".env");
+  if (!existsSync(envPath)) return;
+  try {
+    const text = readFileSync(envPath, "utf8");
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq <= 0) continue;
+      const key = line.slice(0, eq).trim();
+      if (!key || env[key] !== undefined) continue;
+      let val = line.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      env[key] = val;
+    }
+  } catch { /* best effort */ }
+}