@superatomai/sdk-node 0.0.7-s → 0.0.8-cp

package/dist/userResponse/scripts/script-bootstrap.mjs

@@ -5,8 +5,21 @@ import { pathToFileURL } from "url";
 function encodeMessage(msg) {
   return JSON.stringify(msg) + "\n";
 }
+var LineOverflowError = class extends Error {
+  constructor(buffered, limit) {
+    super(`IPC message exceeded ${limit} bytes without a newline (${buffered} buffered) \u2014 aborting to avoid unbounded memory.`);
+    this.buffered = buffered;
+    this.limit = limit;
+    this.name = "LineOverflowError";
+  }
+};
+var DEFAULT_MAX_IPC_BYTES = (() => {
+  const envVal = Number(process.env.SCRIPT_MAX_IPC_BYTES);
+  return Number.isFinite(envVal) && envVal > 0 ? Math.floor(envVal) : 64 * 1024 * 1024;
+})();
 var LineSplitter = class {
-  constructor() {
+  constructor(maxBytes = DEFAULT_MAX_IPC_BYTES) {
+    this.maxBytes = maxBytes;
     this.buffer = "";
   }
   push(chunk) {
@@ -18,6 +31,11 @@ var LineSplitter = class {
       this.buffer = this.buffer.slice(idx + 1);
       if (line.length > 0) lines.push(line);
     }
+    if (this.buffer.length > this.maxBytes) {
+      const buffered = this.buffer.length;
+      this.buffer = "";
+      throw new LineOverflowError(buffered, this.maxBytes);
+    }
     return lines;
   }
   /** Flush any remaining partial data (useful on stream close) */
@@ -28,8 +46,126 @@ var LineSplitter = class {
     return rest;
   }
 };
-function shortId() {
-  return Math.random().toString(36).slice(2, 10);
+
+// src/userResponse/scripts/fmt.ts
+var DASH = "\u2014";
+var DEFAULT_FMT_CONFIG = { locale: "en-IN", currency: "INR" };
+var MONEY_TIERS = {
+  "en-IN": [[1e7, "Cr"], [1e5, "L"]],
+  "hi-IN": [[1e7, "Cr"], [1e5, "L"]]
+};
+var DEFAULT_MONEY_TIERS = [[1e9, "B"], [1e6, "M"]];
+function moneyTiers(locale) {
+  return MONEY_TIERS[locale] ?? DEFAULT_MONEY_TIERS;
+}
+var COUNT_SCALE_MIN = 1e7;
+function toNum(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]|$)/;
+function toDate(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v;
+  if (typeof v === "number") {
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  if (typeof v === "string" && ISO_DATE.test(v.trim())) {
+    const d = new Date(v.trim());
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+function makeFmt(cfg = {}) {
+  const locale = cfg.locale || DEFAULT_FMT_CONFIG.locale;
+  const currency = cfg.currency || DEFAULT_FMT_CONFIG.currency;
+  const group = (n, decimals = 0) => n.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  const symbol = (() => {
+    try {
+      const parts = new Intl.NumberFormat(locale, { style: "currency", currency }).formatToParts(0);
+      return parts.find((p) => p.type === "currency")?.value ?? "";
+    } catch {
+      return "";
+    }
+  })();
+  const scaled = (abs, tiers, decimals) => {
+    for (const [threshold, unit] of tiers) {
+      if (abs >= threshold) return `${group(abs / threshold, decimals)} ${unit}`;
+    }
+    return null;
+  };
+  function money(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const sign = n < 0 ? "-" : "";
+    const abs = Math.abs(n);
+    const tiers = moneyTiers(locale);
+    for (let i = 0; i < tiers.length; i++) {
+      const [threshold, unit] = tiers[i];
+      if (abs < threshold) continue;
+      const value = Number((abs / threshold).toFixed(decimals));
+      const higher = tiers[i - 1];
+      if (higher && value * threshold >= higher[0]) {
+        return `${sign}${symbol}${group(abs / higher[0], decimals)} ${higher[1]}`;
+      }
+      return `${sign}${symbol}${group(abs / threshold, decimals)} ${unit}`;
+    }
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+        minimumFractionDigits: Number.isInteger(n) ? 0 : decimals,
+        maximumFractionDigits: decimals
+      }).format(n);
+    } catch {
+      return `${sign}${symbol}${group(abs, Number.isInteger(abs) ? 0 : decimals)}`;
+    }
+  }
+  function num(v, decimals) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    return group(n, decimals ?? (Number.isInteger(n) ? 0 : 2));
+  }
+  function count(v, decimals = 2) {
+    const n = toNum(v);
+    if (n === null) return DASH;
+    const abs = Math.abs(n);
+    const s = abs >= COUNT_SCALE_MIN ? scaled(abs, moneyTiers(locale), decimals) : null;
+    if (s) return `${n < 0 ? "-" : ""}${s}`;
+    return group(n, Number.isInteger(n) ? 0 : decimals);
+  }
+  function pct(part, whole, decimals = 1) {
+    const p = toNum(part), w = toNum(whole);
+    if (p === null || w === null || w === 0) return DASH;
+    return `${group(p / w * 100, decimals)}%`;
+  }
+  function delta(current, previous, decimals = 1) {
+    const c = toNum(current), p = toNum(previous);
+    if (c === null || p === null || p === 0) return DASH;
+    const change = (c - p) / Math.abs(p) * 100;
+    return `${change >= 0 ? "+" : "-"}${group(Math.abs(change), decimals)}%`;
+  }
+  function date(v) {
+    const d = toDate(v);
+    if (!d) return DASH;
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+  }
+  function range(from, to) {
+    const a = toDate(from), b = toDate(to);
+    if (!a || !b) return DASH;
+    const left = a.getUTCFullYear() === b.getUTCFullYear() ? `${a.getUTCDate()} ${MONTHS[a.getUTCMonth()]}` : date(a);
+    return `${left} \u2013 ${date(b)}`;
+  }
+  function list(items, conjunction = "and") {
+    const parts = (items || []).map((i) => String(i ?? "").trim()).filter(Boolean);
+    if (!parts.length) return DASH;
+    if (parts.length === 1) return parts[0];
+    return `${parts.slice(0, -1).join(", ")} ${conjunction} ${parts[parts.length - 1]}`;
+  }
+  return { money, num, count, pct, delta, date, range, list };
 }
 
 // src/userResponse/scripts/script-bootstrap.ts
@@ -38,8 +174,28 @@ if (!SCRIPT_ARG) {
   sendError("Bootstrap was invoked without a script path.", "compile");
   process.exit(1);
 }
-var pending = /* @__PURE__ */ new Map();
+var BRIDGE_URL = process.env.SCRIPT_BRIDGE_URL;
+var CONTEXT_TOKEN = process.env.SA_CONTEXT_TOKEN;
+var observedPolicies = /* @__PURE__ */ new Set();
+var bridgeHeaders = () => ({
+  "content-type": "application/json",
+  ...CONTEXT_TOKEN ? { "x-sa-context": CONTEXT_TOKEN } : {}
+});
 var executedQueries = [];
+var toolIdCallCounts = {};
+var PREVIEW_MAX_ROWS = 10;
+var PREVIEW_MAX_CHARS = 200;
+var QUERY_ROW_CAP = 250;
+function previewRows(data) {
+  return data.slice(0, PREVIEW_MAX_ROWS).map((row) => {
+    if (!row || typeof row !== "object") return row;
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+      out[k] = typeof v === "string" && v.length > PREVIEW_MAX_CHARS ? v.slice(0, PREVIEW_MAX_CHARS) + "\u2026" : v;
+    }
+    return out;
+  });
+}
 var initResolve = null;
 var initPromise = new Promise((resolve) => {
   initResolve = resolve;
@@ -48,31 +204,87 @@ function buildCtx(init) {
   return {
     now: init.now,
     async query(toolId, sql) {
-      const id = shortId();
+      if (!BRIDGE_URL) throw new Error("SCRIPT_BRIDGE_URL is not set \u2014 script bridge server is not running");
       const startedAt = Date.now();
-      const promise = new Promise((resolve, reject) => {
-        pending.set(id, { resolve, reject, toolId, sql, startedAt });
+      send({ type: "stream", chunk: `
+\u{1F4DD} **Querying ${toolId}:**
+\`\`\`sql
+${sql}
+\`\`\`
+
+` });
+      send({ type: "stream", chunk: `__QUERY_TIMER_START_Executing query__` });
+      const res = await fetch(`${BRIDGE_URL}/query`, {
+        method: "POST",
+        headers: bridgeHeaders(),
+        body: JSON.stringify({ toolId, sql, limit: QUERY_ROW_CAP })
       });
-      send({ type: "query", id, toolId, sql });
-      const result = await promise;
+      const json = await res.json();
       const executionTimeMs = Date.now() - startedAt;
+      for (const p of json?.metadata?.appliedPolicies ?? []) observedPolicies.add(p);
+      send({ type: "stream", chunk: `__QUERY_TIMER_DONE_${(executionTimeMs / 1e3).toFixed(1)}__
+
+` });
+      if (!res.ok || !json.success) {
+        const errMsg = json.error || `Bridge query failed (${res.status})`;
+        send({ type: "stream", chunk: `\u274C **Query failed on ${toolId}:** ${errMsg}
+
+` });
+        throw new Error(errMsg);
+      }
+      let truncated = false;
+      let totalCount;
+      if (json.metadata?.truncated) {
+        truncated = true;
+        totalCount = typeof json.metadata.totalCount === "number" ? json.metadata.totalCount : void 0;
+        const total = json.metadata.totalCount ?? "more";
+        const hasGroupBy = /\bGROUP\s+BY\b/i.test(sql);
+        const explicitLimitMatch = sql.match(/\bLIMIT\s+(\d+)/i);
+        const hasDeliberateLimit = explicitLimitMatch != null && Number(explicitLimitMatch[1]) < QUERY_ROW_CAP;
+        if (hasGroupBy) {
+          send({ type: "stream", chunk: `\u2139\uFE0F Only the top ${QUERY_ROW_CAP} of ${total} grouped rows are returned (query is already aggregated via GROUP BY) \u2014 expected for a top-N request.
+
+` });
+        } else if (hasDeliberateLimit) {
+          send({ type: "stream", chunk: `\u2139\uFE0F Only the ${explicitLimitMatch[1]} rows requested (of ${total} matching) are returned \u2014 expected for a top-N request with an explicit LIMIT.
+
+` });
+        } else {
+          const msg = `ctx.query truncated the result of this query to ${QUERY_ROW_CAP} rows (it matched ${total}). Do NOT compute over raw rows \u2014 AGGREGATE IN SQL (GROUP BY / mode() / mode(...) FILTER (WHERE \u2026) / COUNT(...) FILTER (\u2026) / CASE) so the query returns the final, already-reduced rows, then have getData return those.`;
+          send({ type: "stream", chunk: `\u274C **Result truncated on ${toolId}:** ${msg}
+
+` });
+          throw new Error(msg);
+        }
+      }
+      const data = json.data ?? [];
+      const count = json.count ?? data.length;
+      send({ type: "stream", chunk: `\u2705 **${count} rows from ${toolId}**
+
+` });
+      if (data.length > 0) {
+        send({ type: "stream", chunk: `<DataTable>${JSON.stringify(previewRows(data))}</DataTable>
+
+` });
+      }
+      const callNumber = toolIdCallCounts[toolId] = (toolIdCallCounts[toolId] ?? 0) + 1;
+      const sourceId = callNumber === 1 ? toolId : `${toolId}#${callNumber}`;
       executedQueries.push({
-        sourceId: toolId,
+        sourceId,
         sourceName: toolId,
-        // parent overwrites with the real name
+        // enriched by runner after result arrives
         sql,
-        data: result.data,
-        count: result.count,
-        totalCount: result.metadata?.totalCount,
-        executionTimeMs
+        data,
+        count,
+        executionTimeMs,
+        ...json?.metadata?.appliedPolicies?.length ? { appliedPolicies: json.metadata.appliedPolicies } : {}
       });
-      return { data: result.data, count: result.count };
+      return { data, count, truncated, totalCount };
     },
     /**
      * Call a tool with structured params (typically a direct tool whose
      * fn(params) does not expect a SQL string). Returns whatever the tool
-     * returned — shape is up to the tool. The parent verifies toolId
-     * against the authorized externalTools list before executing.
+     * returned — shape is up to the tool.
      *
      * Use this when you need a pre-built business-logic tool (e.g.,
      * "Calculate Shelf Life") that takes structured input rather than SQL.
@@ -83,18 +295,15 @@ function buildCtx(init) {
      * the array you want to chart.
      */
     async runTool(toolId, params = {}) {
-      const id = shortId();
-      const promise = new Promise((resolveResult, rejectResult) => {
-        pending.set(id, {
-          resolve: (payload) => resolveResult(payload?.result ?? payload),
-          reject: rejectResult,
-          toolId,
-          sql: `-- runTool: ${toolId}`,
-          startedAt: Date.now()
-        });
+      if (!BRIDGE_URL) throw new Error("SCRIPT_BRIDGE_URL is not set \u2014 script bridge server is not running");
+      const res = await fetch(`${BRIDGE_URL}/run-tool`, {
+        method: "POST",
+        headers: bridgeHeaders(),
+        body: JSON.stringify({ toolId, params })
       });
-      send({ type: "run_tool", id, toolId, params });
-      return promise;
+      const json = await res.json();
+      if (!res.ok || !json.success) throw new Error(json.error || `Bridge run-tool failed (${res.status})`);
+      return json.result;
     },
     /**
      * Register a computed dataset. Flows into executedQueries alongside
@@ -121,8 +330,33 @@ function buildCtx(init) {
     }
   };
 }
+function guardCtx(ctx) {
+  const PASSTHROUGH = /* @__PURE__ */ new Set([
+    "then",
+    "catch",
+    "finally",
+    "constructor",
+    "toJSON",
+    "inspect",
+    "valueOf",
+    "toString",
+    "hasOwnProperty",
+    "nodeType"
+  ]);
+  return new Proxy(ctx, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol" || prop in target || PASSTHROUGH.has(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const available = Reflect.ownKeys(target).filter((k) => typeof k === "string").join(", ");
+      throw new TypeError(
+        `ctx.${String(prop)} does not exist. ctx has exactly: ${available}. There are no formatting/parsing/date helpers on ctx \u2014 interpolate ISO date strings straight into the SQL and do date arithmetic in SQL.`
+      );
+    }
+  });
+}
 function send(msg) {
-  process.stdout.write(encodeMessage(msg));
+  return process.stdout.write(encodeMessage(msg));
 }
 function sendError(message, phase, stack) {
   send({ type: "error", message, stack, phase });
@@ -130,7 +364,15 @@ function sendError(message, phase, stack) {
 var splitter = new LineSplitter();
 process.stdin.setEncoding("utf-8");
 process.stdin.on("data", (chunk) => {
-  for (const line of splitter.push(chunk)) {
+  let lines;
+  try {
+    lines = splitter.push(chunk);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    sendError(msg, "runtime");
+    process.exit(1);
+  }
+  for (const line of lines) {
     let msg;
     try {
       msg = JSON.parse(line);
@@ -140,55 +382,71 @@ process.stdin.on("data", (chunk) => {
     handleMessage(msg);
   }
 });
-process.stdin.on("end", () => {
-});
 function handleMessage(msg) {
   switch (msg.type) {
     case "init": {
       if (initResolve) {
         const now = new Date(msg.now || (/* @__PURE__ */ new Date()).toISOString());
         const params = restoreParamTypes(msg.params || {}, msg.paramSchema);
-        initResolve({ params, now });
+        initResolve({ params, now, mode: msg.mode, data: msg.data, datasets: msg.datasets, fmt: msg.fmt, entities: msg.entities, appliedPolicies: msg.appliedPolicies });
         initResolve = null;
       }
       break;
     }
-    case "query_result": {
-      const entry = pending.get(msg.id);
-      if (entry) {
-        pending.delete(msg.id);
-        entry.resolve({ data: msg.data, count: msg.count, metadata: msg.metadata });
-      }
-      break;
+  }
+}
+function collectDatasets(queries) {
+  const out = {};
+  for (const q of queries) {
+    if (q.virtual && q.sourceId.startsWith("computed:")) {
+      out[q.sourceId.slice("computed:".length)] = q.data;
     }
-    case "run_tool_result": {
-      const entry = pending.get(msg.id);
-      if (entry) {
-        pending.delete(msg.id);
-        entry.resolve({ result: msg.result });
-      }
-      break;
+  }
+  return out;
+}
+async function runComponents(mod, data, params, fmtCfg, datasets = {}, entities = [], scope = []) {
+  const getComponents = mod?.getComponents ?? mod?.default?.getComponents;
+  if (typeof getComponents !== "function") return {};
+  try {
+    const out = await getComponents(data, params, makeFmt(fmtCfg), datasets, entities, scope);
+    if (!Array.isArray(out)) {
+      return { componentsError: "getComponents must return an ARRAY of component specs" };
     }
-    case "query_error": {
-      const entry = pending.get(msg.id);
-      if (entry) {
-        pending.delete(msg.id);
-        entry.reject(new Error(msg.error));
-      }
-      break;
+    if (out.some((c) => !c || typeof c !== "object")) {
+      return { componentsError: "every entry getComponents returns must be a component spec object" };
+    }
+    return { components: out };
+  } catch (err) {
+    const e = err;
+    return { componentsError: e?.message || String(err) };
+  }
+}
+async function runAnalysis(mod, data, params, fmtCfg, datasets = {}, entities = [], scope = []) {
+  const getAnalysis = mod?.getAnalysis ?? mod?.default?.getAnalysis;
+  if (typeof getAnalysis !== "function") return {};
+  try {
+    const out = await getAnalysis(data, params, makeFmt(fmtCfg), datasets, entities, scope);
+    if (!out || typeof out !== "object") {
+      return { analysisError: "getAnalysis must return an object with { analysis, summary, method }" };
     }
+    return {
+      analysis: {
+        analysis: typeof out.analysis === "string" ? out.analysis : void 0,
+        summary: Array.isArray(out.summary) ? out.summary.map((s) => String(s)) : void 0,
+        method: typeof out.method === "string" ? out.method : void 0
+      }
+    };
+  } catch (err) {
+    const e = err;
+    return { analysisError: e?.message || String(err) };
   }
 }
 (async () => {
+  let mod;
   let getData;
   try {
-    const mod = await import(pathToFileURL(SCRIPT_ARG).href);
-    getData = mod.getData ?? mod.default;
-    if (typeof getData !== "function") {
-      throw new Error(
-        `Script at ${SCRIPT_ARG} does not export getData \u2014 expected \`export async function getData(ctx, params)\``
-      );
-    }
+    mod = await import(pathToFileURL(SCRIPT_ARG).href);
+    getData = mod.getData ?? (typeof mod.default === "function" ? mod.default : mod.default?.getData);
   } catch (err) {
     const e = err;
     sendError(e.message || String(err), "compile", e.stack);
@@ -196,7 +454,33 @@ function handleMessage(msg) {
     return;
   }
   const init = await initPromise;
-  const ctx = buildCtx(init);
+  if (init.mode === "analysis" || init.mode === "components") {
+    const started = Date.now();
+    const rows = Array.isArray(init.data) ? init.data : [];
+    const ds = init.datasets ?? {};
+    const authored = init.mode === "analysis" ? await runAnalysis(mod, rows, init.params, init.fmt, ds, init.entities, init.appliedPolicies ?? []) : await runComponents(mod, rows, init.params, init.fmt, ds, init.entities, init.appliedPolicies ?? []);
+    const flushedAuthored = send({
+      type: "result",
+      data: [],
+      count: rows.length,
+      executedQueries: [],
+      executionTimeMs: Date.now() - started,
+      sampleRows: [],
+      ...authored
+    });
+    if (flushedAuthored) process.exit(0);
+    else process.stdout.once("drain", () => process.exit(0));
+    return;
+  }
+  if (typeof getData !== "function") {
+    sendError(
+      `Script at ${SCRIPT_ARG} does not export getData \u2014 expected \`export async function getData(ctx, params)\``,
+      "compile"
+    );
+    process.exit(1);
+    return;
+  }
+  const ctx = guardCtx(buildCtx(init));
   const startedAt = Date.now();
   try {
     const raw = await getData(ctx, init.params);
@@ -204,17 +488,28 @@ function handleMessage(msg) {
     const data = normalizeResultData(raw);
     const count = typeof raw?.count === "number" ? raw.count : data.length;
     const sampleRows = data.slice(0, 5);
+    const ds = collectDatasets(executedQueries);
+    const observed = [...observedPolicies];
+    const { analysis, analysisError } = await runAnalysis(mod, data, init.params, init.fmt, ds, init.entities, observed);
+    const { components, componentsError } = await runComponents(mod, data, init.params, init.fmt, ds, init.entities, observed);
     const result = {
       type: "result",
       data,
       count,
       executedQueries,
       executionTimeMs,
-      sampleRows
+      sampleRows,
+      analysis,
+      analysisError,
+      components,
+      componentsError
     };
-    send(result);
-    process.stdout.once("drain", () => process.exit(0));
-    setImmediate(() => process.exit(0));
+    const flushed = send(result);
+    if (flushed) {
+      process.exit(0);
+    } else {
+      process.stdout.once("drain", () => process.exit(0));
+    }
   } catch (err) {
     const e = err;
     sendError(e.message || String(err), "runtime", e.stack);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superatomai/sdk-node",
-  "version": "0.0.7-s",
+  "version": "0.0.8-cp",
   "description": "Node.js TypeScript SDK for Superatom",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map"
   ],
   "keywords": [
     "superatom",
@@ -29,20 +30,26 @@
     "tsup": "^8.0.1",
     "tsx": "^4.20.6",
     "typescript": "^5.3.3",
-    "ws": "^8.18.3"
+    "ws": "^8.21.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.66.0",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
     "@google/generative-ai": "^0.21.0",
     "groq-sdk": "^0.33.0",
     "jsonrepair": "^3.13.1",
     "openai": "^4.77.0",
-    "ws": "^8.18.3",
+    "typebox": "^1.1.38",
+    "ws": "^8.21.0",
     "zod": "^3.25.76"
   },
+  "optionalDependencies": {
+    "@openai/codex-sdk": "0.149.1"
+  },
   "scripts": {
-    "build": "tsup",
+    "build": "tsc --noEmit && tsup",
     "dev": "tsup --watch",
-    "test": "tsx test-sdk.ts"
+    "test": "tsx test-sdk.ts",
+    "type-check": "tsc --noEmit"
   }
 }