@promptev/context-engine 0.0.4 → 0.0.5

package/README.md

@@ -296,6 +296,46 @@ record. Resolve it server-side — on the adapters and the MCP gateway it is an
 still works this release, unscoped and with a `DeprecationWarning`; the next
 release refuses a gated call with no scope.
 
+**Result budget** — the returned `result` is cut to 8,000 characters and 100
+rows unless you say otherwise. Size it to your model's window, or pass `null`
+to lift a limit. `responseMode: "tsv"` works for **any** tool: every array of
+objects in the result — a db tool's `rows`, an HTTP API's `data.items`, a
+function's returned list — comes back as a TSV string under the same key, and
+the budget cuts at whole rows:
+
+```ts
+const out = await engine.executeTool("db_sales", { query: "SELECT * FROM orders" }, {
+  principals: ["user:a"],
+  resultMaxChars: 200_000, // null = no character limit
+  resultMaxRows: null, // per table; a db tool's own max_rows (default 1000) still applies
+  responseMode: "tsv", // -> { success: true, columns: [...], rows: "id\tname\n1\t..." }
+});
+// a cut reports where: { _result_shaping: { rows: { rows_returned: 812, rows_omitted: 188 } } }
+```
+
+In TSV, `\N` is NULL, nested values are compact JSON cells, and tab, newline,
+CR and backslash inside a value are backslash-escaped. Parts of a result that
+aren't arrays of objects stay JSON; a result that *is* one becomes the string
+(wrapped as `{ result, _result_shaping }` when cut). The audit row always keeps
+the original under its own 50KB cap, whatever you pass.
+
+An **http tool** can set its format once, in its config — for every method
+(`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `QUERY`). Omitted, it is `json`; a
+caller's explicit `responseMode` still wins:
+
+```ts
+await engine.registerTool(new ToolConfig({
+  name: "orders",
+  kind: "http",
+  config: { method: "QUERY", url: "https://api.example.com/orders", response_mode: "tsv" }, // "json" (default) | "tsv"
+  acl: ["group:ops"],
+}));
+```
+
+The same conversion is a plain function for anything else:
+`formatResult(result, "tsv")` (and `rowsToTsv(rows)`) from
+`@promptev/context-engine` — `"json"`, the default, returns the input unchanged.
+
 A caller may only register or relabel a tool under principals it holds — filing
 one under another group's ACL is a 403.
 

package/dist/cli.js

@@ -12554,6 +12554,82 @@ var init_registry = __esm({
   "src/tools/registry.ts"() {
   }
 });
+
+// src/tools/response-mode.ts
+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;
+}
+var RESPONSE_MODES;
+var init_response_mode = __esm({
+  "src/tools/response-mode.ts"() {
+    RESPONSE_MODES = ["json", "tsv"];
+  }
+});
 function allowPrivateEgress(engine) {
   return Boolean(engine?.config?.allowPrivateEgress);
 }
@@ -12567,12 +12643,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 capped2 = [...tables.keys()].some((id) => kept.get(id) < sizes.get(id));
+  if (fits()) return [render(), capped2];
+  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 = {
@@ -12582,22 +12736,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) {
@@ -12708,9 +12849,29 @@ function canonicalToPublic(ct) {
     params_schema: ct.paramsSchema
   };
 }
+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`
@@ -12746,6 +12907,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;
@@ -13017,6 +13184,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)) {
@@ -13059,6 +13229,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;
@@ -13082,7 +13253,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;
@@ -13134,6 +13314,7 @@ var init_governance = __esm({
     init_http();
     init_mcp_client();
     init_registry();
+    init_response_mode();
     RESULT_MAX_CHARS = 8e3;
     RESULT_MAX_ROWS = 100;
     UPDATABLE_COLUMNS = /* @__PURE__ */ new Set([
@@ -14415,7 +14596,10 @@ var init_engine = __esm({
           principals: resolvePrincipals(opts.principals, "executeTool"),
           actor: opts.actor,
           source: opts.source ?? "api",
-          approvalScope: opts.approvalScope
+          approvalScope: opts.approvalScope,
+          resultMaxChars: opts.resultMaxChars,
+          resultMaxRows: opts.resultMaxRows,
+          responseMode: opts.responseMode
         });
       }
     };