@promptev/context-engine 0.0.4 → 0.0.5

package/dist/express.js

@@ -944,7 +944,7 @@ var SCHEMAS = {
       url: { type: "string", description: "Endpoint URL, may contain {path} params" },
       method: {
         type: "string",
-        enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+        enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "QUERY"],
         default: "GET"
       },
       headers: {
@@ -980,6 +980,15 @@ var SCHEMAS = {
       llmQueryParameters: {
         type: "object",
         description: "LLM-filled parameters sent as the query string"
+      },
+      // How the response comes back to the caller, whatever the method. `tsv`
+      // turns every array of objects in it into a TSV string (`formatResult`
+      // in tools/response-mode.ts); a caller's explicit `responseMode` wins.
+      response_mode: {
+        type: "string",
+        enum: ["json", "tsv"],
+        default: "json",
+        description: "Return the response as JSON, or its arrays of objects as TSV"
       }
     },
     required: ["url", "method"]
@@ -2507,6 +2516,77 @@ function findTool(tools, callName) {
   return tools.find((t) => t.callName === callName);
 }
 
+// src/tools/response-mode.ts
+var RESPONSE_MODES = ["json", "tsv"];
+function validateResponseMode(value, name = "responseMode") {
+  if (!RESPONSE_MODES.includes(value)) {
+    throw new Error(`${name} must be one of json, tsv, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+function tsvCell(value) {
+  if (value === null || value === void 0) return "\\N";
+  let text;
+  if (typeof value === "string") text = value;
+  else if (value instanceof Date) text = value.toISOString();
+  else if (typeof value === "bigint") text = value.toString();
+  else {
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = String(value);
+    }
+  }
+  return text.replaceAll("\\", "\\\\").replaceAll("	", "\\t").replaceAll("\n", "\\n").replaceAll("\r", "\\r");
+}
+function isPlainObject2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function isTable(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isPlainObject2);
+}
+function tsvLines(rows) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        columns.push(key);
+      }
+    }
+  }
+  return [
+    columns.map(tsvCell).join("	"),
+    ...rows.map((row) => columns.map((c) => tsvCell(row[c])).join("	"))
+  ];
+}
+function collectTables(value, path, out) {
+  if (isTable(value)) {
+    out.set(JSON.stringify(path), { path, lines: tsvLines(value) });
+  } else if (isPlainObject2(value)) {
+    for (const [key, child] of Object.entries(value)) collectTables(child, [...path, key], out);
+  } else if (Array.isArray(value)) {
+    value.forEach((child, index) => {
+      collectTables(child, [...path, index], out);
+    });
+  }
+}
+function buildTsv(value, path, tables, kept) {
+  const id = JSON.stringify(path);
+  const table = tables.get(id);
+  if (table) return table.lines.slice(0, (kept.get(id) ?? 0) + 1).join("\n");
+  if (isPlainObject2(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = buildTsv(v, [...path, k], tables, kept);
+    return out;
+  }
+  if (Array.isArray(value)) return value.map((v, i) => buildTsv(v, [...path, i], tables, kept));
+  return value;
+}
+
 // src/tools/governance.ts
 var RESULT_MAX_CHARS = 8e3;
 var RESULT_MAX_ROWS = 100;
@@ -2538,12 +2618,90 @@ function stripUnderscoreArgs(args) {
   }
   return out;
 }
+function validateResultBudget(name, value, fallback) {
+  if (value === void 0) return fallback;
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new TypeError(`${name} must be a positive integer or null, got ${typeof value}`);
+  }
+  if (value < 1) throw new Error(`${name} must be a positive integer or null, got ${value}`);
+  return value;
+}
+function serialize(value) {
+  try {
+    return JSON.stringify(value) ?? JSON.stringify(String(value));
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}
+function clip(serialized, maxChars) {
+  return {
+    _truncated: serialized.slice(0, maxChars),
+    _original_size: serialized.length,
+    _note: "tool result exceeded the context budget and was truncated"
+  };
+}
+function shapeTsv(result, maxChars, maxRows) {
+  const wrapped = !isPlainObject2(result);
+  const root = wrapped ? { result } : result;
+  const tables = /* @__PURE__ */ new Map();
+  collectTables(root, [], tables);
+  if (!tables.size) return null;
+  const sizes = new Map([...tables].map(([id, t]) => [id, t.lines.length - 1]));
+  const kept = new Map([...sizes].map(([id, n]) => [id, maxRows === null ? n : Math.min(n, maxRows)]));
+  const render = () => {
+    const built = buildTsv(root, [], tables, kept);
+    const notes = {};
+    for (const [id, t] of tables) {
+      const k = kept.get(id);
+      const n = sizes.get(id);
+      if (k < n) notes[t.path.join(".")] = { rows_returned: k, rows_omitted: n - k };
+    }
+    if (Object.keys(notes).length) {
+      built._result_shaping = notes;
+      return built;
+    }
+    return wrapped ? built.result : built;
+  };
+  const fits = () => maxChars === null || serialize(render()).length <= maxChars;
+  const capped = [...tables.keys()].some((id) => kept.get(id) < sizes.get(id));
+  if (fits()) return [render(), capped];
+  const initial = new Map(kept);
+  const tableSize = (id) => tables.get(id).lines.slice(0, kept.get(id) + 1).join("\n").length;
+  const bySize = [...tables.keys()].sort((a, b) => tableSize(b) - tableSize(a));
+  for (const id of bySize) {
+    let lo = 0;
+    let hi = kept.get(id) - 1;
+    let best = null;
+    while (lo <= hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      kept.set(id, mid);
+      if (fits()) {
+        best = mid;
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    if (best !== null) {
+      kept.set(id, best);
+      return [render(), true];
+    }
+    kept.set(id, 0);
+  }
+  for (const [id, n] of initial) kept.set(id, n);
+  return [clip(serialize(render()), maxChars), true];
+}
 function shapeResult(result, opts = {}) {
-  const maxChars = opts.maxChars ?? RESULT_MAX_CHARS;
-  const maxRows = opts.maxRows ?? RESULT_MAX_ROWS;
+  const maxChars = opts.maxChars === void 0 ? RESULT_MAX_CHARS : opts.maxChars;
+  const maxRows = opts.maxRows === void 0 ? RESULT_MAX_ROWS : opts.maxRows;
+  if (opts.responseMode === "tsv") {
+    const tsv = shapeTsv(result, maxChars, maxRows);
+    if (tsv) return tsv;
+  }
   let truncated = false;
   let shaped = result;
-  if (result && typeof result === "object" && Array.isArray(result.rows) && result.rows.length > maxRows) {
+  if (maxRows !== null && result && typeof result === "object" && Array.isArray(result.rows) && result.rows.length > maxRows) {
     const rows = result.rows;
     const kept = rows.slice(0, maxRows);
     shaped = {
@@ -2553,22 +2711,9 @@ function shapeResult(result, opts = {}) {
     };
     truncated = true;
   }
-  let serialized;
-  try {
-    serialized = JSON.stringify(shaped);
-  } catch {
-    serialized = JSON.stringify(String(shaped));
-  }
-  if (serialized.length > maxChars) {
-    return [
-      {
-        _truncated: serialized.slice(0, maxChars),
-        _original_size: serialized.length,
-        _note: "tool result exceeded the context budget and was truncated"
-      },
-      true
-    ];
-  }
+  if (maxChars === null) return [shaped, truncated];
+  const serialized = serialize(shaped);
+  if (serialized.length > maxChars) return [clip(serialized, maxChars), true];
   return [shaped, truncated];
 }
 function redactToolResult(result, policy, opts) {
@@ -2671,9 +2816,29 @@ async function mergedTools(engine, sourceId) {
   const functions = Object.values(engine._functionTools ?? {});
   return [...persisted, ...functions];
 }
+function configuredResponseMode(ct, config) {
+  if (ct.kind !== "http" || config.response_mode == null) return "json";
+  try {
+    return validateResponseMode(config.response_mode, "config.response_mode");
+  } catch {
+    console.warn(
+      `tool ${ct.callName} has an unknown config response_mode ${JSON.stringify(config.response_mode)}; returning json`
+    );
+    return "json";
+  }
+}
+function checkConfigResponseMode(kind, config) {
+  if (kind !== "http" || !config || config.response_mode == null) return;
+  try {
+    validateResponseMode(config.response_mode, "config.response_mode");
+  } catch (exc) {
+    throw new ConfigTemplateError(exc.message);
+  }
+}
 async function registerTool(engine, tc) {
   canonicalFromConfig(tc);
   const config = tc.config ?? {};
+  checkConfigResponseMode(tc.kind, config);
   if (containsSentinel(config)) {
     throw new ConfigTemplateError(
       `config contains the ${JSON.stringify(REDACTED_SENTINEL)} placeholder \u2014 a redacted template cannot be registered as a new tool; re-enter the secret values`
@@ -2709,6 +2874,12 @@ async function updateTool(engine, id, opts) {
   if (!row || !aclVisible(row.acl != null ? [...row.acl] : null, principals)) {
     throw new EngineActionError(`tool not found: ${id}`);
   }
+  if ("config" in fields) {
+    checkConfigResponseMode(
+      "kind" in fields ? fields.kind : row.kind,
+      fields.config
+    );
+  }
   const sets = [];
   const params = [];
   let i = 1;
@@ -2999,6 +3170,9 @@ function warnUnscopedApproval(callName) {
 async function executeTool(engine, callName, args, opts = {}) {
   const runtimeArgs = args ?? {};
   const approvalScope = validateApprovalScope(opts.approvalScope);
+  const resultMaxChars = validateResultBudget("resultMaxChars", opts.resultMaxChars, RESULT_MAX_CHARS);
+  const resultMaxRows = validateResultBudget("resultMaxRows", opts.resultMaxRows, RESULT_MAX_ROWS);
+  let responseMode = opts.responseMode === void 0 || opts.responseMode === null ? null : validateResponseMode(opts.responseMode);
   const ct = findTool(await mergedTools(engine, opts.sourceId ?? null), callName);
   if (!ct) throw new EngineActionError(`tool not found: ${callName}`);
   if (!toolVisible(ct, opts.principals ?? null)) {
@@ -3041,6 +3215,7 @@ async function executeTool(engine, callName, args, opts = {}) {
   if (ct.kind !== "function" && ct.id != null) {
     config = await decryptCtConfig(engine, ct.id);
   }
+  responseMode ??= configuredResponseMode(ct, config);
   const actorType = opts.actor?.type ?? null;
   const actorId = opts.actor?.id ?? null;
   let rawResult = null;
@@ -3064,7 +3239,16 @@ async function executeTool(engine, callName, args, opts = {}) {
         hooks: engine.hooks
       });
       rawResult = redacted;
-      [shaped, truncated] = shapeResult(rawResult);
+      let toShape = rawResult;
+      if (responseMode === "tsv" && ct.kind === "db" && isPlainObject2(rawResult)) {
+        const { text: _preview, ...rest } = rawResult;
+        toShape = rest;
+      }
+      [shaped, truncated] = shapeResult(toShape, {
+        maxChars: resultMaxChars,
+        maxRows: resultMaxRows,
+        responseMode
+      });
     } catch (e) {
       exc = e;
       success = false;