@superatomai/sdk-node 0.0.68-dsp → 0.0.69-dsp

package/dist/index.js

@@ -52,11 +52,13 @@ __export(index_exports, {
   UIBlock: () => UIBlock,
   UILogCollector: () => UILogCollector,
   UserManager: () => UserManager,
+  analyticsClient: () => analyticsClient,
   answerCatalogForBinding: () => answerCatalogForBinding,
   answerComponents: () => answerComponents,
   anthropicLLM: () => anthropicLLM,
   assertReadOnlySql: () => assertReadOnlySql,
   bindContext: () => bindContext,
+  bridgePreamble: () => bridgePreamble,
   captureContext: () => captureContext,
   clearContextTokens: () => clearContextTokens,
   contextTokenCount: () => contextTokenCount,
@@ -72,6 +74,7 @@ __export(index_exports, {
   geminiLLM: () => geminiLLM,
   getCodingAgent: () => getCodingAgent,
   getCodingAgentsConfig: () => getCodingAgentsConfig,
+  getPiSessionState: () => getPiSessionState,
   getRequestContext: () => getRequestContext,
   groqLLM: () => groqLLM,
   hybridRerank: () => hybridRerank,
@@ -84,9 +87,11 @@ __export(index_exports, {
   mintContextToken: () => mintContextToken,
   normalizeScriptBody: () => normalizeScriptBody,
   onAgentRun: () => onAgentRun,
+  onPiSessionUpdate: () => onPiSessionUpdate,
   openaiLLM: () => openaiLLM,
   policiesFromConfig: () => policiesFromConfig,
   projectForDatasetBinding: () => projectForDatasetBinding,
+  promptLoader: () => promptLoader,
   queryCache: () => queryCache,
   registerCodingAgentCollection: () => registerCodingAgentCollection,
   registerCodingAgents: () => registerCodingAgents,
@@ -108,7 +113,8 @@ __export(index_exports, {
   userPromptErrorLogger: () => userPromptErrorLogger,
   validateComponentSpec: () => validateComponentSpec,
   withCapturedContext: () => withCapturedContext,
-  writeBridgeShims: () => writeBridgeShims
+  writeBridgeShims: () => writeBridgeShims,
+  writeShims: () => writeShims
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -911,6 +917,101 @@ var CodingAgentAbortRequestMessageSchema = import_zod3.z.object({
   type: import_zod3.z.literal("CODING_AGENT_ABORT_REQ"),
   payload: CodingAgentAbortRequestPayloadSchema
 });
+var DashBuilderRequestPayloadSchema = import_zod3.z.object({
+  /** The conversation. One per dashboard program, and the abort key. */
+  dashboardId: import_zod3.z.string(),
+  /** What the person said. */
+  text: import_zod3.z.string(),
+  /**
+   * A panel the person pointed at before typing.
+   *
+   * Its `Panel` id, the same key a saved arrangement stores against. Optional
+   * because most turns are about the dashboard rather than one panel of it, and
+   * carried as a field rather than folded into `text` so the transcript shows
+   * what the person actually wrote.
+   */
+  panelId: import_zod3.z.string().optional(),
+  projectId: import_zod3.z.string().optional(),
+  userId: import_zod3.z.string().optional()
+});
+var DashBuilderRequestMessageSchema = import_zod3.z.object({
+  id: import_zod3.z.string(),
+  from: MessageParticipantSchema,
+  type: import_zod3.z.literal("DASH_BUILDER_REQ"),
+  payload: DashBuilderRequestPayloadSchema
+});
+var DashBuilderUpdateSchema = import_zod3.z.discriminatedUnion("type", [
+  import_zod3.z.object({ type: import_zod3.z.literal("state"), running: import_zod3.z.boolean() }),
+  import_zod3.z.object({ type: import_zod3.z.literal("user"), text: import_zod3.z.string(), at: import_zod3.z.number() }),
+  /**
+   * The tail of an assistant message that is still being written.
+   *
+   * Append-only and never part of the transcript: the `assistant` update that
+   * follows carries the same prose in full, so a client shows the accumulated
+   * deltas while a turn runs and drops them the moment the real message lands.
+   * A turn here runs for minutes, and without this the pane sits empty for all
+   * of it.
+   */
+  import_zod3.z.object({ type: import_zod3.z.literal("delta"), text: import_zod3.z.string() }),
+  import_zod3.z.object({ type: import_zod3.z.literal("assistant"), text: import_zod3.z.string(), at: import_zod3.z.number() }),
+  import_zod3.z.object({ type: import_zod3.z.literal("tool"), text: import_zod3.z.string(), at: import_zod3.z.number() }),
+  import_zod3.z.object({ type: import_zod3.z.literal("error"), text: import_zod3.z.string(), at: import_zod3.z.number() })
+]);
+var DashBuilderStreamPayloadSchema = import_zod3.z.object({
+  dashboardId: import_zod3.z.string(),
+  /**
+   * Monotonic per turn, so re-delivery is harmless.
+   *
+   * Copied from dashboard-agent rather than assumed unnecessary: duplicate and
+   * out-of-order delivery were observed there on long-running requests and were
+   * never explained by anything in the send/receive path itself. A turn here
+   * runs for minutes, which is the same exposure.
+   */
+  seq: import_zod3.z.number(),
+  update: DashBuilderUpdateSchema
+});
+var DashBuilderStreamMessageSchema = import_zod3.z.object({
+  id: import_zod3.z.string().optional(),
+  from: MessageParticipantSchema,
+  type: import_zod3.z.literal("DASH_BUILDER_STREAM"),
+  payload: DashBuilderStreamPayloadSchema
+});
+var DashBuilderAbortRequestPayloadSchema = import_zod3.z.object({
+  dashboardId: import_zod3.z.string()
+});
+var DashBuilderAbortRequestMessageSchema = import_zod3.z.object({
+  id: import_zod3.z.string().optional(),
+  from: MessageParticipantSchema,
+  type: import_zod3.z.literal("DASH_BUILDER_ABORT_REQ"),
+  payload: DashBuilderAbortRequestPayloadSchema
+});
+var DashComponentPropSchema = import_zod3.z.union([
+  import_zod3.z.string(),
+  import_zod3.z.object({
+    description: import_zod3.z.string(),
+    importance: import_zod3.z.enum(["required", "recommended", "optional"]).optional(),
+    default: import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean()]).optional(),
+    caution: import_zod3.z.string().optional(),
+    group: import_zod3.z.string().optional()
+  })
+]);
+var DashComponentSchema = import_zod3.z.object({
+  name: import_zod3.z.string(),
+  kind: import_zod3.z.string(),
+  purpose: import_zod3.z.string(),
+  props: import_zod3.z.record(DashComponentPropSchema).optional(),
+  useWhen: import_zod3.z.string().optional(),
+  notes: import_zod3.z.string().optional()
+});
+var DashContractResponsePayloadSchema = import_zod3.z.object({
+  components: import_zod3.z.array(DashComponentSchema)
+});
+var DashContractResponseMessageSchema = import_zod3.z.object({
+  id: import_zod3.z.string(),
+  from: MessageParticipantSchema,
+  type: import_zod3.z.literal("DASH_CONTRACT_RES"),
+  payload: DashContractResponsePayloadSchema
+});
 var ReportCompRequestPayloadSchema = import_zod3.z.object({
   prompt: import_zod3.z.string(),
   userId: import_zod3.z.string().optional(),
@@ -3835,7 +3936,7 @@ var TaggedStreamBuffer = class extends StreamBuffer {
   }
 };
 function streamDelay(ms = STREAM_DELAY_MS) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function withProgressHeartbeat(operation, progressMessage, streamBuffer, intervalMs = PROGRESS_HEARTBEAT_INTERVAL_MS) {
   if (!streamBuffer.hasCallback()) {
@@ -11016,7 +11117,7 @@ var Semaphore = class {
         `Script execution at capacity (${this.max} running, ${this.waiters.length} queued). Try again shortly.`
       );
     }
-    return new Promise((resolve2) => this.waiters.push(resolve2));
+    return new Promise((resolve3) => this.waiters.push(resolve3));
   }
   release() {
     const next = this.waiters.shift();
@@ -11146,7 +11247,7 @@ FIX: pass every required parameter to execute_script, or give it a default in wr
   }
 }
 function executeInSubprocess(scriptPath, params, paramSchema, externalTools, streamBuffer, timeoutMs, signal, mode, analysisData, analysisDatasets, entities, appliedPolicies) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const tsxBin = resolveTsxBinary();
     const bootstrap = resolveBootstrapPath();
     const contextToken = mintContextToken();
@@ -11202,7 +11303,7 @@ function executeInSubprocess(scriptPath, params, paramSchema, externalTools, str
       clearTimeout(timer);
       if (signal && onAbort) signal.removeEventListener("abort", onAbort);
       cleanup();
-      resolve2(r);
+      resolve3(r);
     };
     const timer = setTimeout(() => {
       finish({
@@ -18901,7 +19002,25 @@ RENDERING REQUIREMENT (overrides the default choice of component): ${carriedRequ
         }
       }
       if (!usedLightweight) {
-        logger.warn(`[AgentFlow] Component generation produced nothing \u2014 returning the analysis without a dashboard`);
+        logger.warn(`[AgentFlow] Component generation produced no components \u2014 returning the analysis without a dashboard`);
+      }
+    }
+    if (matchedComponents.length === 0) {
+      const fallbackText = (agentResponse.text || "").replace(/<DashboardComponents>[\s\S]*?<\/DashboardComponents>/g, "").trim();
+      if (fallbackText) {
+        logger.info(`[AgentFlow] No components \u2014 wrapping the analysis in DynamicMarkdownBlock`);
+        matchedComponents = [{
+          id: "dynamic-markdown-block",
+          name: "DynamicMarkdownBlock",
+          type: "MarkdownBlock",
+          description: "Text response rendered as markdown",
+          props: { content: fallbackText }
+        }];
+        layoutTitle = "";
+        layoutDescription = "";
+        noDataAnswer = true;
+      } else {
+        logger.warn(`[AgentFlow] No components and no analysis text \u2014 returning an empty result`);
       }
     }
     const queryMap = {};
@@ -19842,12 +19961,13 @@ async function handleUserPromptRequest(data, components, sendMessage, anthropicA
       id: `comp_${Math.random().toString(36).substring(2, 8)}`
     }));
   }
+  const { trace: _trace, ...dataWithoutTrace } = response.data ?? {};
   sendDataResponse4(
     response.id || data.id,
     {
       success: response.success,
       errors: response.errors,
-      data: response.data,
+      data: response.data ? dataWithoutTrace : response.data,
       uiBlockId: response.uiBlockId,
       threadId: response.threadId
     },
@@ -20044,6 +20164,26 @@ async function handleComponentListResponse(data, storeComponents, collections) {
   }
 }
 
+// src/handlers/dash-contract-response.ts
+async function handleDashContractResponse(data, storeDashContract, collections) {
+  const parsed = DashContractResponseMessageSchema.safeParse(data);
+  if (!parsed.success) {
+    logger.error("[DashContract] Invalid message \u2014 ignoring");
+    return;
+  }
+  const { components } = parsed.data.payload;
+  storeDashContract(components);
+  const register = collections?.["dashboard-builder"]?.["registerContract"];
+  if (!register) return;
+  try {
+    await register({ components });
+  } catch (error) {
+    logger.warn(
+      `[DashContract] Collection refused the contract: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 // src/handlers/workflow-list-response.ts
 async function handleWorkflowListResponse(data, storeWorkflows) {
   try {
@@ -24441,11 +24581,257 @@ ${marker}
   };
 }
 
+// src/codingAgent/drivers/pi.ts
+var dynamicImport2 = new Function("specifier", "return import(specifier)");
+var piModulePromise = null;
+function loadPi() {
+  if (!piModulePromise) {
+    piModulePromise = dynamicImport2("@earendil-works/pi-coding-agent").catch((err) => {
+      piModulePromise = null;
+      throw new Error(`@earendil-works/pi-coding-agent is not installed, so the pi harness is unavailable. (${err?.message ?? err})`);
+    });
+  }
+  return piModulePromise;
+}
+var authAndRegistry = null;
+function getAuthAndRegistry() {
+  if (!authAndRegistry) {
+    authAndRegistry = loadPi().then(({ AuthStorage, ModelRegistry }) => {
+      const authStorage = AuthStorage.create();
+      return { authStorage, modelRegistry: ModelRegistry.create(authStorage) };
+    });
+  }
+  return authAndRegistry;
+}
+var DEFAULT_PROVIDER = "openai-codex";
+var DEFAULT_MODEL_ID = process.env.PI_AGENT_MODEL || "gpt-5.5";
+var KNOWN_UNUSABLE_MODEL_IDS = /* @__PURE__ */ new Set(["gpt-5.3-codex-spark"]);
+async function resolveModel(modelRegistry, spec) {
+  const [provider, modelId] = spec?.includes("/") ? [spec.slice(0, spec.indexOf("/")), spec.slice(spec.indexOf("/") + 1)] : [spec || DEFAULT_PROVIDER, void 0];
+  const available = modelRegistry.getAvailable().filter((m) => m.provider === provider);
+  const wanted = modelId ?? (spec ? void 0 : DEFAULT_MODEL_ID);
+  const exact = wanted && (modelRegistry.find(provider, wanted) ?? available.find((m) => m.id === wanted));
+  if (exact && modelRegistry.hasConfiguredAuth(exact)) return exact;
+  const usable = available.filter((m) => !KNOWN_UNUSABLE_MODEL_IDS.has(m.id));
+  if (usable.length) return usable[0];
+  if (available.length) return available[0];
+  throw new Error(
+    `No model available from "${provider}". Authorise it in a terminal on this machine: run \`pi\`, then \`/login\`.`
+  );
+}
+function emptyUsage2() {
+  return { inputTokens: 0, outputTokens: 0, reasoningTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, toolCalls: 0 };
+}
+var BUFFER_CAP2 = 64e3;
+var EVENT_CAP2 = 600;
+function normEvent2(ev) {
+  switch (ev.type) {
+    case "tool_execution_start":
+      return { kind: "command", id: ev.toolCallId, command: ev.toolName ? `${ev.toolName} ${jsonPreview(ev.args)}` : void 0, status: "in_progress" };
+    case "tool_execution_end":
+      return { kind: "command", id: ev.toolCallId, status: ev.isError ? "failed" : "completed", done: true, output: textOf(ev.result) };
+    default:
+      return null;
+  }
+}
+function jsonPreview(v) {
+  if (v == null) return "";
+  try {
+    return JSON.stringify(v).slice(0, 160);
+  } catch {
+    return "";
+  }
+}
+function textOf(content) {
+  const blocks = content?.content ?? content;
+  if (!Array.isArray(blocks)) return typeof content === "string" ? content : "";
+  return blocks.filter((b) => b?.type === "text").map((b) => String(b.text ?? "")).join("").trim();
+}
+var TRANSCRIPT_CAP = 400;
+var sessionListeners = /* @__PURE__ */ new Set();
+function onPiSessionUpdate(listener) {
+  sessionListeners.add(listener);
+  return () => sessionListeners.delete(listener);
+}
+function getPiSessionState(sessionKey) {
+  const live = liveSessions.get(sessionKey);
+  return live ? { running: live.running, transcript: live.transcript } : void 0;
+}
+function publish(sessionKey, live, entry) {
+  live.transcript.push(entry);
+  if (live.transcript.length > TRANSCRIPT_CAP) live.transcript.splice(0, live.transcript.length - TRANSCRIPT_CAP);
+  for (const listener of sessionListeners) listener(sessionKey, entry);
+}
+var liveSessions = /* @__PURE__ */ new Map();
+function newSessionId() {
+  return `pi_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var IDLE_TIMEOUT_MS = Number(process.env.PI_AGENT_IDLE_MS ?? 30 * 60 * 1e3);
+var sweeper = null;
+function startSweeper() {
+  if (sweeper) return;
+  sweeper = setInterval(() => {
+    const cutoff = Date.now() - IDLE_TIMEOUT_MS;
+    for (const [key, live] of liveSessions) {
+      if (live.running || live.lastActive > cutoff) continue;
+      live.session.dispose();
+      liveSessions.delete(key);
+    }
+    if (liveSessions.size === 0 && sweeper) {
+      clearInterval(sweeper);
+      sweeper = null;
+    }
+  }, 6e4);
+  sweeper.unref?.();
+}
+function createPiSession(opts) {
+  let running = false;
+  let sessionKey = opts.resumeId && liveSessions.has(opts.resumeId) ? opts.resumeId : void 0;
+  async function ensureSession() {
+    const existing = sessionKey ? liveSessions.get(sessionKey) : void 0;
+    if (existing) return existing;
+    const { createAgentSession, SessionManager } = await loadPi();
+    const { authStorage, modelRegistry } = await getAuthAndRegistry();
+    const model = await resolveModel(modelRegistry, opts.model);
+    const { session } = await createAgentSession({
+      cwd: opts.cwd,
+      sessionManager: SessionManager.inMemory(),
+      authStorage,
+      modelRegistry,
+      model,
+      tools: opts.tools ?? ["bash"]
+    });
+    sessionKey = newSessionId();
+    const live = { session, running: false, transcript: [], lastActive: Date.now(), eventLog: [], buf: "" };
+    liveSessions.set(sessionKey, live);
+    startSweeper();
+    return live;
+  }
+  async function runTurn(prompt, handlers, signal) {
+    const startedAt = Date.now();
+    const usage = emptyUsage2();
+    let status = "completed";
+    let error;
+    const finish = (live2) => ({
+      status,
+      answer: status === "error" || status === "aborted" ? "" : live2?.session.getLastAssistantText()?.trim() ?? "",
+      ms: Date.now() - startedAt,
+      usage,
+      error,
+      sessionId: sessionKey
+    });
+    if (signal?.aborted) {
+      status = "aborted";
+      return finish();
+    }
+    const live = await ensureSession();
+    const key = sessionKey;
+    live.running = true;
+    live.lastActive = Date.now();
+    publish(key, live, { at: Date.now(), kind: "user", text: prompt });
+    const before = live.session.getSessionStats();
+    const onAbort = () => {
+      void live.session.abort();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const emit = (chunk) => {
+      live.buf = (live.buf + chunk).slice(-BUFFER_CAP2);
+      handlers?.onOutput?.(chunk);
+    };
+    const unsubscribe = live.session.subscribe((ev) => {
+      if (ev.type === "message_update" && ev.assistantMessageEvent?.type === "text_delta") {
+        const delta = ev.assistantMessageEvent.delta;
+        if (delta) {
+          emit(delta);
+          handlers?.onNarration?.(delta);
+        }
+        return;
+      }
+      if (ev.type === "tool_execution_start" || ev.type === "tool_execution_end") {
+        if (ev.type === "tool_execution_end") usage.toolCalls++;
+        const event = normEvent2(ev);
+        if (!event) return;
+        live.eventLog.push(event);
+        if (live.eventLog.length > EVENT_CAP2) live.eventLog.shift();
+        handlers?.onEvent?.(event);
+        publish(key, live, { at: Date.now(), kind: "activity", event });
+        if (ev.type === "tool_execution_start") emit(`
+\u2192 ${ev.toolName ?? "tool"} ${jsonPreview(ev.args)}
+`);
+        return;
+      }
+    });
+    try {
+      if (signal?.aborted) {
+        status = "aborted";
+        return finish(live);
+      }
+      await live.session.prompt(prompt);
+      const err = live.session.agent.state.errorMessage;
+      if (err) {
+        status = signal?.aborted ? "aborted" : "error";
+        error = err;
+      } else if (signal?.aborted) {
+        status = "aborted";
+      }
+    } catch (err) {
+      status = signal?.aborted ? "aborted" : "error";
+      error = err?.message ?? String(err);
+    } finally {
+      unsubscribe();
+      signal?.removeEventListener("abort", onAbort);
+      live.running = false;
+      live.lastActive = Date.now();
+    }
+    const after = live.session.getSessionStats();
+    usage.inputTokens = Math.max(0, after.tokens.input - before.tokens.input);
+    usage.outputTokens = Math.max(0, after.tokens.output - before.tokens.output);
+    usage.cacheReadTokens = Math.max(0, after.tokens.cacheRead - before.tokens.cacheRead);
+    usage.cacheWriteTokens = Math.max(0, after.tokens.cacheWrite - before.tokens.cacheWrite);
+    usage.costUSD = Math.max(0, after.cost - before.cost);
+    handlers?.onUsage?.({ ...usage });
+    const result = finish(live);
+    publish(key, live, result.status === "error" ? { at: Date.now(), kind: "error", text: result.error } : { at: Date.now(), kind: "assistant", text: result.answer });
+    return result;
+  }
+  return {
+    harness: "pi",
+    kind: "events",
+    async run(prompt, handlers, signal) {
+      if (running) throw new Error("This pi session already has a turn in flight.");
+      running = true;
+      try {
+        return await runTurn(prompt, handlers, signal);
+      } finally {
+        running = false;
+      }
+    },
+    events: () => sessionKey ? liveSessions.get(sessionKey)?.eventLog ?? [] : [],
+    buffer: () => sessionKey ? liveSessions.get(sessionKey)?.buf ?? "" : "",
+    busy: () => running,
+    sessionId: () => sessionKey,
+    // Abandon for real — drop the live session so the next run starts fresh.
+    reset: () => {
+      if (sessionKey) {
+        liveSessions.get(sessionKey)?.session.dispose();
+        liveSessions.delete(sessionKey);
+      }
+      sessionKey = void 0;
+    },
+    // Local-only, same as the codex driver: the live session stays in the
+    // module map so a later run with this sessionId can still resume it.
+    dispose: () => {
+    }
+  };
+}
+
 // src/codingAgent/factory.ts
 function createCodingAgentSession(harness, opts) {
   switch (harness) {
     case "codex":
       return createCodexSession(opts);
+    case "pi":
+      return createPiSession(opts);
     default:
       throw new Error(`Unknown coding-agent harness: ${harness}`);
   }
@@ -24847,9 +25233,6 @@ Fix ONLY that, and rewrite the same file at the same path. Do not re-run any que
   }
 }
 
-// src/codingAgent/tools/bridge-shims.ts
-var fs9 = __toESM(require("fs"));
-
 // src/codingAgent/tools/read-only-sql.ts
 var WRITE_KEYWORDS = [
   "insert",
@@ -24904,9 +25287,45 @@ ${stripSqlNoise.toString()}
 ${assertReadOnlySql.toString().replace("export function", "function")}
 `;
 
+// src/codingAgent/tools/shims.ts
+var fs9 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
+var resolve2 = (target, name) => typeof target === "string" ? path10.join(target, name) : target.pathTo(name);
+function writeShims(defs, target) {
+  for (const def of defs) {
+    const file = resolve2(target, def.name);
+    fs9.writeFileSync(file, def.body, "utf-8");
+    fs9.chmodSync(file, 493);
+  }
+  return defs.map((def) => ({ name: `./${def.name}`, summary: def.summary }));
+}
+function bridgePreamble(bridgeUrl, constants = {}) {
+  const declared = Object.entries(constants).map(([name, value]) => `const ${name} = ${JSON.stringify(value)};`).join("\n");
+  return `const BRIDGE = ${JSON.stringify(bridgeUrl)};
+${declared}
+
+function post(path, payload) {
+  return fetch(BRIDGE + path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Request failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    try { return JSON.parse(text); } catch { console.error(text); process.exit(1); }
+  }).catch((e) => { console.error('Could not reach the backend: ' + (e && e.message)); process.exit(1); });
+}
+`;
+}
+
 // src/codingAgent/tools/bridge-shims.ts
 function writeBridgeShims(ws, opts) {
   const maxRows = opts.maxRows ?? 200;
+  const directTools = opts.directTools ?? [];
+  const entityTypes = opts.entityTypes ?? [];
+  const conceptCatalog = opts.conceptCatalog ?? [];
+  const hasKnowledgeBase = !!opts.knowledgeBase;
+  const hasSearchableSource = opts.sources.some((s) => s.searchable);
   const query = `#!/usr/bin/env node
 // Read-only SQL against a data source. Generated per run \u2014 do not edit.
 ${READ_ONLY_SQL_SOURCE}
@@ -24916,7 +25335,7 @@ const CONTEXT_TOKEN = ${JSON.stringify(opts.contextToken ?? null)};
 
 const [toolId, sql, limitArg] = process.argv.slice(2);
 if (!toolId || !sql) {
-  console.error('usage: ./query "<toolId>" "<sql>" [limit]\\nRun ./sources for the toolIds.');
+  console.error('usage: node ./query "<toolId>" "<sql>" [limit]\\nRun: node ./sources \u2014 for the toolIds.');
   process.exit(2);
 }
 try { assertReadOnlySql(sql); } catch (e) { console.error(String(e.message || e)); process.exit(2); }
@@ -24958,24 +25377,189 @@ fetch(BRIDGE + '/query', {
   })
   .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
 `;
-  const sources = `#!/usr/bin/env node
-// The data sources you can query, and the exact toolId for ./query.
-console.log(${JSON.stringify(JSON.stringify(opts.sources, null, 2))});
+  const runTool = `#!/usr/bin/env node
+// Invoke a pre-built business-logic tool. Generated per run \u2014 do not edit.
+const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
+
+const [toolId, paramsArg] = process.argv.slice(2);
+if (!toolId) {
+  console.error('usage: node ./run-tool "<toolId>" [\\'<json params>\\']\\nRun: node ./sources \u2014 for the toolIds and their params.');
+  process.exit(2);
+}
+let params = {};
+if (paramsArg) {
+  try { params = JSON.parse(paramsArg); }
+  catch (e) { console.error('params must be JSON: ' + String(e.message || e)); process.exit(2); }
+}
+
+fetch(BRIDGE + '/run-tool', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ toolId, params }),
+})
+  .then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Tool call failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    let p; try { p = JSON.parse(text); } catch { console.log(text); return; }
+    if (p && p.error) { console.error(String(p.error)); process.exit(1); }
+    console.log(JSON.stringify(p.result ?? p, null, 2));
+  })
+  .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
+`;
+  const schemaSearch = `#!/usr/bin/env node
+// Keyword search over a large source's schema \u2014 call this BEFORE writing SQL
+// against a "searchable" source (see ./sources); its schema is too big to
+// have been shown to you in full, and guessing column names wastes a turn on
+// a failed query. Generated per run \u2014 do not edit.
+const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
+
+const [toolId, ...keywords] = process.argv.slice(2);
+if (!toolId || !keywords.length) {
+  console.error('usage: node ./schema-search "<toolId>" <keyword> [keyword...]\\nRun: node ./sources \u2014 for which toolIds are searchable.');
+  process.exit(2);
+}
+
+fetch(BRIDGE + '/schema-search', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ toolId, keywords }),
+})
+  .then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Schema search failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    let p; try { p = JSON.parse(text); } catch { console.log(text); return; }
+    if (p && p.error) { console.error(String(p.error)); process.exit(1); }
+    console.log(p.result ?? p);
+  })
+  .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
+`;
+  const resolveEntities = `#!/usr/bin/env node
+// Resolve named things (customers, projects, people, ...) to their real
+// database ids, and business concepts to table/column/join facts \u2014 one round
+// trip, either half optional. Call this BEFORE writing SQL about anything
+// named in the question; never guess or fuzzy-match a name yourself.
+// Generated per run \u2014 do not edit.
+const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
+
+const [argJson] = process.argv.slice(2);
+if (!argJson) {
+  console.error('usage: node ./resolve-entities \\'{"mentions":[{"text":"..."}],"entityTypes":["..."]}\\'\\nRun: node ./sources \u2014 for which entity types exist. Either field may be omitted.');
+  process.exit(2);
+}
+let args;
+try { args = JSON.parse(argJson); }
+catch (e) { console.error('argument must be JSON: ' + String(e.message || e)); process.exit(2); }
+
+fetch(BRIDGE + '/resolve-entities', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ mentions: args.mentions ?? [], entityTypes: args.entityTypes ?? [] }),
+})
+  .then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Entity resolution failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    let p; try { p = JSON.parse(text); } catch { console.log(text); return; }
+    if (p && p.error) { console.error(String(p.error)); process.exit(1); }
+    console.log(JSON.stringify(p.result ?? p, null, 2));
+  })
+  .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
+`;
+  const conceptCatalogShim = `#!/usr/bin/env node
+// Every verified concept \u2014 name, aliases, and what it is for. No bodies: the
+// whole vocabulary in one call, so you know what exists and which ones bear on
+// the question, instead of guessing a name into ./run-tool "concept". Read it,
+// then fetch the ones that apply. Call this once, early. There is no search
+// step and nothing to search: this is the complete list.
+// Generated per run \u2014 do not edit.
+const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
+
+fetch(BRIDGE + '/concept-catalog', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' })
+  .then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Concept catalog fetch failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    let p; try { p = JSON.parse(text); } catch { console.log(text); return; }
+    if (p && p.error) { console.error(String(p.error)); process.exit(1); }
+    console.log(JSON.stringify(p.result ?? p, null, 2));
+  })
+  .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
 `;
-  for (const [name, body] of [["query", query], ["sources", sources]]) {
-    const p = ws.pathTo(name);
-    fs9.writeFileSync(p, body, "utf-8");
-    fs9.chmodSync(p, 493);
+  const knowledgeBaseShim = `#!/usr/bin/env node
+// Free-form domain knowledge (gotchas, join paths, table/column meanings) \u2014
+// lower priority than the concept catalog: check ./concept-catalog / the
+// concept tool first for anything with a formal business-rule meaning, use
+// this directly for everything else.
+//
+// No args lists every node; get fetches the bodies. There is no search step
+// and nothing to search \u2014 the corpus is tens of nodes with one short title
+// each, same as ./concept-catalog. Generated per run \u2014 do not edit.
+const BRIDGE = ${JSON.stringify(opts.bridgeUrl)};
+
+const [argJson] = process.argv.slice(2);
+let args;
+if (!argJson) {
+  args = { method: 'catalog' };
+} else {
+  try { args = JSON.parse(argJson); }
+  catch (e) {
+    console.error('argument must be JSON: ' + String(e.message || e));
+    console.error('usage: node ./knowledge-base            \u2192 every node: id, title, category, tags');
+    console.error('       node ./knowledge-base \\'{"method":"get","ids":[12,31]}\\'  \u2192 their content');
+    process.exit(2);
   }
 }
 
+fetch(BRIDGE + '/knowledge-base', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(args),
+})
+  .then(async (r) => {
+    const text = await r.text();
+    if (!r.ok) { console.error('Knowledge base lookup failed (' + r.status + '): ' + text.slice(0, 2000)); process.exit(1); }
+    let p; try { p = JSON.parse(text); } catch { console.log(text); return; }
+    if (p && p.error) { console.error(String(p.error)); process.exit(1); }
+    console.log(JSON.stringify(p.result ?? p, null, 2));
+  })
+  .catch((e) => { console.error('Could not reach the data bridge: ' + (e && e.message)); process.exit(1); });
+`;
+  const sources = `#!/usr/bin/env node
+// The data sources you can query with ./query (and search with
+// ./schema-search when "searchable" is true), the pre-built tools you can
+// invoke with ./run-tool, and the entity types ./resolve-entities can
+// resolve names against. The concept catalog itself is NOT repeated here \u2014
+// run ./concept-catalog for that.
+console.log(${JSON.stringify(
+    JSON.stringify({
+      sources: opts.sources,
+      directTools,
+      entityTypes,
+      ...conceptCatalog.length ? { conceptCount: conceptCatalog.length } : {},
+      ...hasKnowledgeBase ? { knowledgeBase: true } : {}
+    }, null, 2)
+  )});
+`;
+  const files = [
+    ["sources", sources, "(no arguments) \u2014 what you can query, which of those are searchable, the pre-built tools, and the entity types."],
+    ["query", query, '"<toolId>" "<sql>" [limit] \u2014 read-only SQL against one source. The only way to see real data. ./sources for the toolIds.']
+  ];
+  if (opts.conceptCatalog) files.push(["concept-catalog", conceptCatalogShim, '(no arguments) \u2014 every verified concept: name, aliases, what it is for. No bodies. Read this before the schema; fetch bodies with ./run-tool "concept".']);
+  if (hasKnowledgeBase) files.push(["knowledge-base", knowledgeBaseShim, `[ '{"method":"get","ids":[12,31]}' ] \u2014 free-form domain knowledge: gotchas, join paths, what a column really holds. No arguments lists every node; get fetches bodies. Ranks below concepts, above your own reading of the schema.`]);
+  if (entityTypes.length) files.push(["resolve-entities", resolveEntities, `'{"mentions":[{"text":"<name>"}]}' \u2014 turn a name a person typed into the value stored in the data. Run it before filtering on any proper noun.`]);
+  if (hasSearchableSource) files.push(["schema-search", schemaSearch, `"<toolId>" <keyword> [keyword...] \u2014 keyword search over a large source's schema. Required before writing SQL against a "searchable" source \u2014 its schema was never shown to you in full.`]);
+  if (directTools.length) files.push(["run-tool", runTool, `"<toolId>" '<json params>' \u2014 invoke a pre-built business-logic tool, including "concept" get/run. ./sources lists each one's parameters.`]);
+  return writeShims(
+    files.map(([name, body, summary]) => ({ name, body, summary })),
+    ws
+  );
+}
+
 // src/codingAgent/triggers.ts
 var fs10 = __toESM(require("fs"));
-var path10 = __toESM(require("path"));
+var path11 = __toESM(require("path"));
 var EVENT_BURST_CAP = 200;
 var capEvents = (events) => events.length > EVENT_BURST_CAP ? events.slice(-EVENT_BURST_CAP) : events;
 function statePath2(agentId) {
-  return path10.join(getCodingAgentsConfig().runtimeDir, agentId, "_triggers.json");
+  return path11.join(getCodingAgentsConfig().runtimeDir, agentId, "_triggers.json");
 }
 function loadTriggerState(agentId) {
   let raw;
@@ -25000,7 +25584,7 @@ function loadTriggerState(agentId) {
 function saveTriggerState(agentId, state) {
   try {
     const p = statePath2(agentId);
-    fs10.mkdirSync(path10.dirname(p), { recursive: true });
+    fs10.mkdirSync(path11.dirname(p), { recursive: true });
     fs10.writeFileSync(p, JSON.stringify(state, null, 2));
   } catch (err) {
     logger.warn(`[CodingAgent:${agentId}] failed to persist trigger state: ${err?.message ?? err}`);
@@ -25138,12 +25722,12 @@ function describeTriggers() {
 
 // src/codingAgent/collection.ts
 var fs11 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
+var path12 = __toESM(require("path"));
 function isChattable(agent) {
   return agent.mode !== "task";
 }
 function registerCodingAgentCollection(sdk, config2 = {}) {
-  const runtimeDir = config2.runtimeDir || process.env.CODING_AGENT_RUNTIME_DIR || path11.join(process.cwd(), ".coding-agent-runtime");
+  const runtimeDir = config2.runtimeDir || process.env.CODING_AGENT_RUNTIME_DIR || path12.join(process.cwd(), ".coding-agent-runtime");
   const defaultHarness = config2.harness || process.env.CODING_AGENT_HARNESS || "codex";
   const sessions = /* @__PURE__ */ new Map();
   const running = /* @__PURE__ */ new Set();
@@ -25203,7 +25787,7 @@ function registerCodingAgentCollection(sdk, config2 = {}) {
           ...record.status === "skipped" ? { error: `${def.title} is in the middle of a run \u2014 try again in a moment.` } : record.error ? { error: record.error } : {}
         };
       }
-      const cwd = path11.join(runtimeDir, "threads", threadId);
+      const cwd = path12.join(runtimeDir, "threads", threadId);
       fs11.mkdirSync(cwd, { recursive: true });
       let session = sessions.get(threadId);
       if (!session) {
@@ -25369,6 +25953,134 @@ async function handleCodingAgentRequest(data, collections, sendMessage) {
   }
 }
 
+// src/dashBuilder/handler.ts
+var inFlightAborts4 = /* @__PURE__ */ new Map();
+var recentlyAborted4 = /* @__PURE__ */ new Map();
+var ABORT_TOMBSTONE_TTL_MS4 = 3e4;
+function setAbortTombstone4(dashboardId) {
+  const now = Date.now();
+  recentlyAborted4.set(dashboardId, now);
+  for (const [key, ts] of recentlyAborted4) {
+    if (now - ts > ABORT_TOMBSTONE_TTL_MS4) recentlyAborted4.delete(key);
+  }
+}
+function consumeAbortTombstone4(dashboardId) {
+  const ts = recentlyAborted4.get(dashboardId);
+  if (ts === void 0) return false;
+  recentlyAborted4.delete(dashboardId);
+  return Date.now() - ts <= ABORT_TOMBSTONE_TTL_MS4;
+}
+function handleDashBuilderAbort(data, sendMessage) {
+  const parsed = DashBuilderAbortRequestMessageSchema.safeParse(data);
+  if (!parsed.success) {
+    logger.warn("[DashBuilderAbort] Invalid message \u2014 ignoring");
+    return;
+  }
+  const { payload, from } = parsed.data;
+  const { dashboardId } = payload;
+  const controller = inFlightAborts4.get(dashboardId);
+  if (controller) {
+    controller.abort();
+    inFlightAborts4.delete(dashboardId);
+    logger.info(`[DashBuilderAbort] Aborted in-flight turn for ${dashboardId}`);
+  } else {
+    setAbortTombstone4(dashboardId);
+    logger.info(`[DashBuilderAbort] No in-flight turn for ${dashboardId} \u2014 tombstoned`);
+  }
+  try {
+    sendMessage({
+      id: `dash_builder_aborted_${dashboardId}`,
+      type: "DASH_BUILDER_ABORTED",
+      from: { type: "data-agent" },
+      to: { type: "runtime", id: from.id },
+      payload: { dashboardId }
+    });
+  } catch (err) {
+    logger.warn(
+      `[DashBuilderAbort] Failed to send abort ack: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function handleDashBuilderRequest(data, collections, sendMessage) {
+  return runWithMessageIdentity(data, () => handleDashBuilderRequestInner(data, collections, sendMessage));
+}
+async function handleDashBuilderRequestInner(data, collections, sendMessage) {
+  const parsed = DashBuilderRequestMessageSchema.safeParse(data);
+  if (!parsed.success) {
+    logger.error("[DashBuilderReq] Invalid message:", JSON.stringify(parsed.error.errors));
+    return;
+  }
+  const { id, payload, from } = parsed.data;
+  const { dashboardId, text, panelId, projectId, userId } = payload;
+  const wsId = from.id;
+  const respond = (res) => {
+    sendMessage({
+      id,
+      type: "DASH_BUILDER_RES",
+      from: { type: "data-agent" },
+      to: { type: "runtime", id: wsId },
+      payload: res
+    });
+  };
+  if (!collections?.["dashboard-builder-agent"]?.["prompt"]) {
+    respond({
+      started: false,
+      error: "The dashboard builder is not available in this environment (collection 'dashboard-builder-agent' not registered)."
+    });
+    return;
+  }
+  const abortController = new AbortController();
+  if (consumeAbortTombstone4(dashboardId)) {
+    abortController.abort();
+    logger.info(`[DashBuilderReq] ${dashboardId} was pre-aborted \u2014 starting cancelled`);
+  }
+  inFlightAborts4.set(dashboardId, abortController);
+  let seq = 0;
+  const stream = (update) => {
+    try {
+      sendMessage({
+        /**
+         * Keyed by this request's id, not by dashboardId.
+         *
+         * dashboardId repeats across every turn in a conversation, so a
+         * listener that failed to clean up would keep matching future turns
+         * forever and interleave their output. A per-request id means a
+         * stale listener simply never matches anything again.
+         */
+        id: `dash_builder_stream_${id}`,
+        type: "DASH_BUILDER_STREAM",
+        from: { type: "data-agent" },
+        to: { type: "runtime", id: wsId },
+        payload: { dashboardId, seq: seq++, update }
+      });
+    } catch (err) {
+      logger.warn(
+        `[DashBuilderReq] Stream send failed (socket may be closed): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  };
+  try {
+    const result = await collections["dashboard-builder-agent"]["prompt"]({
+      dashboardId,
+      text,
+      panelId,
+      projectId,
+      userId,
+      signal: abortController.signal,
+      onUpdate: stream
+    });
+    respond(result ?? { started: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`[DashBuilderReq] ${dashboardId} failed to start: ${message}`);
+    respond({ started: false, error: message });
+  } finally {
+    if (inFlightAborts4.get(dashboardId) === abortController) {
+      inFlightAborts4.delete(dashboardId);
+    }
+  }
+}
+
 // src/reportComp/types.ts
 var DEFAULT_REPORT_COMP_MODELS = {
   anthropic: "anthropic/claude-haiku-4-5-20251001",
@@ -25867,21 +26579,21 @@ Fixed SQL query:`;
 }
 
 // src/reportComp/index.ts
-var inFlightAborts4 = /* @__PURE__ */ new Map();
-var recentlyAborted4 = /* @__PURE__ */ new Map();
-var ABORT_TOMBSTONE_TTL_MS4 = 3e4;
-function setAbortTombstone4(reportId) {
+var inFlightAborts5 = /* @__PURE__ */ new Map();
+var recentlyAborted5 = /* @__PURE__ */ new Map();
+var ABORT_TOMBSTONE_TTL_MS5 = 3e4;
+function setAbortTombstone5(reportId) {
   const now = Date.now();
-  recentlyAborted4.set(reportId, now);
-  for (const [key, ts] of recentlyAborted4) {
-    if (now - ts > ABORT_TOMBSTONE_TTL_MS4) recentlyAborted4.delete(key);
+  recentlyAborted5.set(reportId, now);
+  for (const [key, ts] of recentlyAborted5) {
+    if (now - ts > ABORT_TOMBSTONE_TTL_MS5) recentlyAborted5.delete(key);
   }
 }
-function consumeAbortTombstone4(reportId) {
-  const ts = recentlyAborted4.get(reportId);
+function consumeAbortTombstone5(reportId) {
+  const ts = recentlyAborted5.get(reportId);
   if (ts === void 0) return false;
-  recentlyAborted4.delete(reportId);
-  return Date.now() - ts <= ABORT_TOMBSTONE_TTL_MS4;
+  recentlyAborted5.delete(reportId);
+  return Date.now() - ts <= ABORT_TOMBSTONE_TTL_MS5;
 }
 function handleReportCompAbort(data, sendMessage) {
   const parseResult = ReportCompAbortRequestMessageSchema.safeParse(data);
@@ -25892,13 +26604,13 @@ function handleReportCompAbort(data, sendMessage) {
   const { payload, from } = parseResult.data;
   const { reportId } = payload;
   const wsId = from.id;
-  const controller = inFlightAborts4.get(reportId);
+  const controller = inFlightAborts5.get(reportId);
   if (controller) {
     controller.abort();
-    inFlightAborts4.delete(reportId);
+    inFlightAborts5.delete(reportId);
     logger.info(`[ReportCompAbort] Aborted in-flight run for report ${reportId}`);
   } else {
-    setAbortTombstone4(reportId);
+    setAbortTombstone5(reportId);
     logger.info(`[ReportCompAbort] No in-flight run for report ${reportId} \u2014 tombstoned`);
   }
   try {
@@ -25944,11 +26656,11 @@ var processReportCompRequest = async (data, components, _sendMessage, anthropicA
   const trace = createRunTrace();
   const abortController = new AbortController();
   if (reportId) {
-    if (consumeAbortTombstone4(reportId)) {
+    if (consumeAbortTombstone5(reportId)) {
       abortController.abort();
       logger.info(`[REPORT_COMP_REQ] reportId=${reportId} was pre-aborted \u2014 starting cancelled`);
     }
-    inFlightAborts4.set(reportId, abortController);
+    inFlightAborts5.set(reportId, abortController);
   }
   let llmResponse;
   try {
@@ -25969,7 +26681,7 @@ var processReportCompRequest = async (data, components, _sendMessage, anthropicA
       trace
     );
   } finally {
-    if (reportId) inFlightAborts4.delete(reportId);
+    if (reportId) inFlightAborts5.delete(reportId);
   }
   const wasAborted = abortController.signal.aborted || !llmResponse.success && Array.isArray(llmResponse.errors) && llmResponse.errors.includes("aborted");
   if (wasAborted) {
@@ -27678,16 +28390,16 @@ function buildDashboardAgentTools(sdk, signal, trace) {
 }
 
 // src/dashboardAgent/collection.ts
-var dynamicImport2 = new Function("specifier", "return import(specifier)");
-var piModulePromise = null;
-function loadPi() {
-  if (!piModulePromise) piModulePromise = dynamicImport2("@earendil-works/pi-coding-agent");
-  return piModulePromise;
-}
-var authAndRegistry = null;
-function getAuthAndRegistry() {
-  if (!authAndRegistry) {
-    authAndRegistry = loadPi().then(({ AuthStorage, ModelRegistry }) => {
+var dynamicImport3 = new Function("specifier", "return import(specifier)");
+var piModulePromise2 = null;
+function loadPi2() {
+  if (!piModulePromise2) piModulePromise2 = dynamicImport3("@earendil-works/pi-coding-agent");
+  return piModulePromise2;
+}
+var authAndRegistry2 = null;
+function getAuthAndRegistry2() {
+  if (!authAndRegistry2) {
+    authAndRegistry2 = loadPi2().then(({ AuthStorage, ModelRegistry }) => {
       const authStorage = AuthStorage.create();
       const modelRegistry = ModelRegistry.create(authStorage);
       const proxyRoot = process.env.SUPERATOM_LLM_PROXY_URL;
@@ -27704,7 +28416,7 @@ function getAuthAndRegistry() {
       return { authStorage, modelRegistry };
     });
   }
-  return authAndRegistry;
+  return authAndRegistry2;
 }
 async function preResolveSchema(sdk, tool, intent, projectId) {
   const tier = tool.schemaTier;
@@ -27917,8 +28629,8 @@ ${fullPrompt}
       return { success: false, error: "aborted" };
     }
     try {
-      const { createAgentSession, SessionManager } = await loadPi();
-      const { authStorage, modelRegistry } = await getAuthAndRegistry();
+      const { createAgentSession, SessionManager } = await loadPi2();
+      const { authStorage, modelRegistry } = await getAuthAndRegistry2();
       let model;
       const explicitProvider = config2.provider || process.env.PI_AGENT_PROVIDER;
       const explicitModel = config2.model || process.env.PI_AGENT_MODEL;
@@ -28316,6 +29028,15 @@ var SuperatomSDK = class {
     // since an outage of unknown length shouldn't grow this without limit.
     this.pendingOutbox = [];
     this.MAX_OUTBOX_SIZE = 50;
+    /**
+     * The dashboard contract, as registered by the browser bundle that holds it.
+     *
+     * Empty until a client has connected and pushed it. That is a real state and
+     * callers must handle it rather than treat it as an empty contract: an empty
+     * list means "nobody has told us yet", not "there are no components", and
+     * building against it would produce a dashboard that can import nothing.
+     */
+    this.dashContract = [];
     if (config2.logLevel) {
       logger.setLogLevel(config2.logLevel);
     }
@@ -28432,7 +29153,7 @@ var SuperatomSDK = class {
       logger.info("Already connected to WebSocket");
       return Promise.resolve();
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       try {
         const url = new URL(this.url);
         if (this.apiKey) {
@@ -28448,7 +29169,7 @@ var SuperatomSDK = class {
           logger.info("WebSocket connected successfully");
           this.startHeartbeat();
           this.flushPendingOutbox();
-          resolve2();
+          resolve3();
         });
         this.ws.addEventListener("message", (event) => {
           this.handleMessage(event.data);
@@ -28536,6 +29257,13 @@ var SuperatomSDK = class {
             logger.error("Failed to handle component list request:", error);
           });
           break;
+        /* The dashboard contract, pushed by the bundle that holds it — on
+         * connect and again on every reconnect. See types.ts. */
+        case "DASH_CONTRACT_RES":
+          handleDashContractResponse(parsed, (c) => this.storeDashContract(c), this.collections).catch((error) => {
+            logger.error("Failed to handle dashboard contract:", error);
+          });
+          break;
         case "WORKFLOW_LIST_RES":
           handleWorkflowListResponse(parsed, (wf) => this.setWorkflows(wf)).catch((error) => {
             logger.error("Failed to handle workflow list request:", error);
@@ -28602,6 +29330,16 @@ var SuperatomSDK = class {
         case "CODING_AGENT_ABORT_REQ":
           handleCodingAgentAbort(parsed, (msg) => this.send(msg));
           break;
+        // The dashboard BUILDER's conversation — distinct from
+        // DASHBOARD_AGENT_REQ, which drives the older JSON-DSL flow.
+        case "DASH_BUILDER_REQ":
+          handleDashBuilderRequest(parsed, this.collections, (msg) => this.send(msg)).catch((error) => {
+            logger.error("Failed to handle dash builder request:", error);
+          });
+          break;
+        case "DASH_BUILDER_ABORT_REQ":
+          handleDashBuilderAbort(parsed, (msg) => this.send(msg));
+          break;
         case "REPORT_COMP_REQ":
           handleReportCompRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.geminiApiKey, this.openaiApiKey, this.llmProviders, this.collections, this.tools, this.dashCompModels).catch((error) => {
             logger.error("Failed to handle report comp request:", error);
@@ -28824,6 +29562,14 @@ var SuperatomSDK = class {
   getComponents() {
     return this.components;
   }
+  storeDashContract(components) {
+    this.dashContract = components;
+    logger.info(`Dashboard contract registered: ${components.length} components`);
+  }
+  /** The registered dashboard contract. Empty means "not registered yet". */
+  getDashContract() {
+    return this.dashContract;
+  }
   /**
    * Set tools for the SDK instance
    */
@@ -28946,11 +29692,13 @@ var SuperatomSDK = class {
   UIBlock,
   UILogCollector,
   UserManager,
+  analyticsClient,
   answerCatalogForBinding,
   answerComponents,
   anthropicLLM,
   assertReadOnlySql,
   bindContext,
+  bridgePreamble,
   captureContext,
   clearContextTokens,
   contextTokenCount,
@@ -28966,6 +29714,7 @@ var SuperatomSDK = class {
   geminiLLM,
   getCodingAgent,
   getCodingAgentsConfig,
+  getPiSessionState,
   getRequestContext,
   groqLLM,
   hybridRerank,
@@ -28978,9 +29727,11 @@ var SuperatomSDK = class {
   mintContextToken,
   normalizeScriptBody,
   onAgentRun,
+  onPiSessionUpdate,
   openaiLLM,
   policiesFromConfig,
   projectForDatasetBinding,
+  promptLoader,
   queryCache,
   registerCodingAgentCollection,
   registerCodingAgents,
@@ -29002,6 +29753,7 @@ var SuperatomSDK = class {
   userPromptErrorLogger,
   validateComponentSpec,
   withCapturedContext,
-  writeBridgeShims
+  writeBridgeShims,
+  writeShims
 });
 //# sourceMappingURL=index.js.map