@buoy-gg/agent-core 7.0.41 → 7.0.43

package/lib/module/catalog/toProviderTools.js

@@ -1,139 +1,2 @@
-"use strict";
-
-/**
- * Catalog -> provider tool definitions.
- *
- * WHY ONE TOOL PER BUOY TOOL, NOT ONE PER ACTION: tool-selection accuracy
- * degrades past roughly 30-50 tools. Buoy has ~179 actions across 22 tools, so
- * a 1:1 mapping is far past the point where the model starts picking wrong.
- * Each Buoy tool therefore becomes ONE provider tool whose `action` property is
- * an enum, with the per-action summaries folded into that enum's description.
- *
- * `params` stays an open object at the provider boundary — a discriminated
- * union across 179 branches is unusable by any model and unreadable by a human.
- * The real per-action schema is enforced one layer in, by `validateParams`,
- * which returns a structured error the model can correct on the next turn.
- * That is strictly stronger than the MCP server's `z.record(z.unknown())`,
- * which validates nothing.
- */
-import { paramsLine } from "./signature";
-
-/**
- * Provider-agnostic tool definition; the adapters reshape it per protocol.
- *
- * The description comes in three forms because the two protocols cap it
- * differently. Anthropic takes `description` whole. OpenAI (and Azure, and
- * every OpenAI-compatible gateway) caps a function description at 1024
- * chars, and the catalog renders the summary first and the `Actions:` list
- * LAST — so trimming `description` to fit dropped every action line for 23
- * of 24 tools (the 24th kept one line of sixteen), and a model on that
- * protocol saw a summary cut mid-sentence plus a bare `action` enum. Hence
- * the split: `summaryDescription` is the part that fits the cap,
- * `actionsBlock` goes into the `action` property's description, which
- * nothing caps. `description` stays their concatenation
- * so the Anthropic request is byte-identical to what it was.
- */
-
-/**
- * Both Anthropic and OpenAI cap tool names at `[a-zA-Z0-9_-]`, so Buoy's
- * dashed ids survive but the `custom:<id>` sync namespace does not. Anthropic's
- * docs say 64 chars while its reference schema says 128 — we code to 64.
- */
-const MAX_TOOL_NAME = 64;
-export function toProviderToolName(toolId) {
-  return `buoy_${toolId.replace(/[^a-zA-Z0-9_-]/g, "_")}`.slice(0, MAX_TOOL_NAME);
-}
-
-/** Reverse of {@link toProviderToolName}, resolved against the live catalog. */
-export function fromProviderToolName(name, catalog) {
-  return catalog.find(t => toProviderToolName(t.toolId) === name)?.toolId;
-}
-
-/**
- * One line per action, in the `action` enum's description. This is where the
- * model actually learns what each action does, so it carries the effect and
- * the release caveat inline rather than hiding them in a separate field the
- * model never sees.
- */
-function actionLine(a, isRelease) {
-  const bits = [`${a.action} — ${a.summary}`];
-  if (a.effect === "destructive") bits.push("[DESTRUCTIVE]");else if (a.effect === "write") bits.push("[changes state]");
-  if (isRelease && a.release !== "works") {
-    bits.push(`[UNAVAILABLE in this build: ${a.release}]`);
-  }
-  if (a.requires?.length) bits.push(`[needs: ${a.requires.join(", ")}]`);
-  // The field names, from the SAME schema `validateParams` enforces. Without
-  // them the model reconstructs parameter names from prose and invents one on
-  // ~18% of param-carrying calls (measured across three agents); five of the
-  // commonest misses are patched up by `normalizeParams`, the rest just fail.
-  // `buoy_ui` already ships its signatures for exactly this reason — see the
-  // note above `signature()` in catalog/signature.ts.
-  const sig = paramsLine(a.params);
-  return sig ? `${bits.join(" ")}\n    ${sig}` : bits.join(" ");
-}
-export function toProviderTools(catalog, opts = {}) {
-  const {
-    availableToolIds,
-    availableActions,
-    isRelease = false,
-    hideUnavailable = false
-  } = opts;
-  const tools = [];
-  for (const tool of catalog) {
-    if (availableToolIds && !availableToolIds.includes(tool.toolId)) continue;
-    const live = availableActions?.[tool.toolId];
-    // An engine-served action needs no adapter to advertise it — the engine
-    // is the adapter — so it rides with the tool whenever the tool is here.
-    let actions = live ? tool.actions.filter(a => live.includes(a.action) || a.servedBy === "engine") : tool.actions;
-    if (isRelease && hideUnavailable) {
-      actions = actions.filter(a => a.release === "works");
-    }
-    if (actions.length === 0) continue;
-
-    // The summary ALONE is what has to fit OpenAI's 1024-char cap (it does for
-    // 23 of 24 tools); the availability caveat rides with the actions block,
-    // which nothing caps. Concatenated they are the same bytes as before.
-    const summaryDescription = tool.summary;
-    // These prose lines look like the expensive part of the catalog and are
-    // the CHEAPEST part of it. Measured against a real tokenizer (fal ->
-    // gpt-4o-mini): the whole catalog is 79,601 chars but only 7,902 tokens
-    // — 10.1 chars/token, because English prose is what BPE compresses best.
-    // An index that replaced these lines with a bare list of action names
-    // sent 48% fewer characters and cost MORE tokens (7,986), since dotted
-    // camelCase identifiers tokenize at ~5 chars/token. Do not "shrink" this
-    // by counting characters; measure tokens or leave it alone.
-    const actionsBlock = [tool.unavailableWhen ? `Unavailable when: ${tool.unavailableWhen}` : "", "Actions:", ...actions.map(a => `- ${actionLine(a, isRelease)}`)].join("\n");
-    // No blank line between the two: the single-list render this replaced
-    // filtered its "" separator out, and this string is the prefix Anthropic
-    // caches — it must not move by a byte.
-    const desc = [summaryDescription, actionsBlock].filter(Boolean).join("\n");
-    const inputExamples = actions.flatMap(a => a.inputExamples ?? []);
-    tools.push({
-      name: toProviderToolName(tool.toolId),
-      ...(inputExamples.length ? {
-        inputExamples
-      } : {}),
-      description: desc,
-      summaryDescription,
-      actionsBlock,
-      inputSchema: {
-        type: "object",
-        properties: {
-          action: {
-            type: "string",
-            enum: actions.map(a => a.action),
-            description: "Which action to run. See the list in this tool's description."
-          },
-          params: {
-            type: "object",
-            description: "Arguments for the action. Each action's `params:` line in this tool's description lists its exact fields — `*` marks a required one. Send EXACTLY those names; a field that is not listed is rejected."
-          }
-        },
-        required: ["action"],
-        additionalProperties: false
-      }
-    });
-  }
-  return tools;
-}
-//# sourceMappingURL=toProviderTools.js.map
+"use strict";import{paramsLine as h}from"./signature";const v=64;export function toProviderToolName(e){return`buoy_${e.replace(/[^a-zA-Z0-9_-]/g,"_")}`.slice(0,v)}export function fromProviderToolName(e,s){return s.find(t=>toProviderToolName(t.toolId)===e)?.toolId}function b(e,s){const t=[`${e.action} \u2014 ${e.summary}`];if(e.effect==="destructive")t.push("[DESTRUCTIVE]");else if(e.effect==="write")t.push("[changes state]");if(s&&e.release!=="works"){t.push(`[UNAVAILABLE in this build: ${e.release}]`)}if(e.requires?.length)t.push(`[needs: ${e.requires.join(", ")}]`);const r=h(e.params);return r?`${t.join(" ")}
+    ${r}`:t.join(" ")}export function toProviderTools(e,s={}){const{availableToolIds:t,availableActions:r,isRelease:a=false,hideUnavailable:f=false}=s;const l=[];for(const o of e){if(t&&!t.includes(o.toolId))continue;const c=r?.[o.toolId];let n=c?o.actions.filter(i=>c.includes(i.action)||i.servedBy==="engine"):o.actions;if(a&&f){n=n.filter(i=>i.release==="works")}if(n.length===0)continue;const u=o.summary;const p=[o.unavailableWhen?`Unavailable when: ${o.unavailableWhen}`:"","Actions:",...n.map(i=>`- ${b(i,a)}`)].join("\n");const m=[u,p].filter(Boolean).join("\n");const d=n.flatMap(i=>i.inputExamples??[]);l.push({name:toProviderToolName(o.toolId),...d.length?{inputExamples:d}:{},description:m,summaryDescription:u,actionsBlock:p,inputSchema:{type:"object",properties:{action:{type:"string",enum:n.map(i=>i.action),description:"Which action to run. See the list in this tool's description."},params:{type:"object",description:"Arguments for the action. Each action's `params:` line in this tool's description lists its exact fields \u2014 `*` marks a required one. Send EXACTLY those names; a field that is not listed is rejected."}},required:["action"],additionalProperties:false}})}return l}

package/lib/module/catalog/validateParams.js

@@ -1,124 +1 @@
-"use strict";
-
-/**
- * A deliberately small JSON Schema validator.
- *
- * Buoy's adapters validate nothing — every handler takes `params?: unknown` and
- * hand-casts (`(params as { id?: string })?.id`), so a wrong shape becomes an
- * undefined read, and an LLM omitting an optional flag can do real damage:
- * `zustand.setState` defaults `replace ?? true`, so calling it without
- * `replace` REPLACES the entire store rather than merging it.
- *
- * So the agent validates before it dispatches. The point is not spec
- * compliance — it is that a rejection comes back to the model as a readable
- * error naming the expected schema, which it can fix on the next turn. That is
- * why this covers exactly the subset `JsonSchema` describes and nothing more:
- * a rule the validator silently skips is a rule that isn't enforced.
- */
-
-function typeOf(v) {
-  if (v === null) return "null";
-  if (Array.isArray(v)) return "array";
-  return typeof v;
-}
-function checkType(value, type) {
-  switch (type) {
-    case "integer":
-      return typeof value === "number" && Number.isInteger(value);
-    case "number":
-      return typeof value === "number" && Number.isFinite(value);
-    case "null":
-      return value === null;
-    case "array":
-      return Array.isArray(value);
-    case "object":
-      return typeOf(value) === "object";
-    default:
-      return typeof value === type;
-  }
-}
-function validate(value, schema, path, errors) {
-  if (schema.anyOf?.length) {
-    const anyOk = schema.anyOf.some(s => {
-      const sub = [];
-      validate(value, s, path, sub);
-      return sub.length === 0;
-    });
-    if (!anyOk) {
-      const kinds = schema.anyOf.map(s => s.type ?? "?").join(" | ");
-      errors.push(`${path}: expected ${kinds}, got ${typeOf(value)}`);
-    }
-    return;
-  }
-  if (schema.type && !checkType(value, schema.type)) {
-    errors.push(`${path}: expected ${schema.type}, got ${typeOf(value)}`);
-    return;
-  }
-  if (schema.enum && !schema.enum.includes(value)) {
-    errors.push(`${path}: expected one of ${schema.enum.map(e => JSON.stringify(e)).join(", ")}, got ${JSON.stringify(value)}`);
-    return;
-  }
-  if (schema.type === "array" && Array.isArray(value)) {
-    if (schema.minItems !== undefined && value.length < schema.minItems) {
-      errors.push(`${path}: expected at least ${schema.minItems} item(s), got ${value.length}`);
-    }
-    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
-      errors.push(`${path}: expected at most ${schema.maxItems} item(s), got ${value.length}`);
-    }
-    if (schema.items) {
-      value.forEach((item, i) => validate(item, schema.items, `${path}[${i}]`, errors));
-    }
-    return;
-  }
-  if (schema.type === "object" && typeOf(value) === "object") {
-    const obj = value;
-    for (const key of schema.required ?? []) {
-      if (obj[key] === undefined) errors.push(`${path}.${key}: required`);
-    }
-    if (schema.properties) {
-      for (const [key, sub] of Object.entries(schema.properties)) {
-        if (obj[key] !== undefined) validate(obj[key], sub, `${path}.${key}`, errors);
-      }
-      // Only flag unknown keys when the schema says so. Several adapters read
-      // params they never documented, and rejecting an extra key the handler
-      // happens to use would break a call that would have worked.
-      if (schema.additionalProperties === false) {
-        const known = new Set(Object.keys(schema.properties));
-        for (const key of Object.keys(obj)) {
-          if (!known.has(key)) errors.push(`${path}.${key}: unexpected property`);
-        }
-      }
-    }
-  }
-}
-export function validateParams(params, schema) {
-  const errors = [];
-  // A no-param action called with nothing is the common case, not an error.
-  const value = params === undefined || params === null ? {} : params;
-  validate(value, schema, "params", errors);
-  return {
-    ok: errors.length === 0,
-    errors
-  };
-}
-
-/**
- * Fill in documented defaults the model left out.
- *
- * This is the counter-measure to the omitted-flag class of bug. Several Buoy
- * actions invert the usual assumption — `focus-inspector.setTracking` reads
- * `params?.enabled !== false`, so calling it with `{}` turns tracking ON — and
- * the catalog records the real default. Applying it explicitly means the model
- * omitting a flag produces the documented behaviour rather than the accidental
- * one.
- */
-export function applyDefaults(params, schema) {
-  const out = typeOf(params) === "object" ? {
-    ...params
-  } : {};
-  for (const [key, sub] of Object.entries(schema.properties ?? {})) {
-    if (out[key] === undefined && sub.default !== undefined) out[key] = sub.default;
-  }
-  return out;
-}
-//# sourceMappingURL=validateParams.js.map
+"use strict";function u(t){if(t===null)return"null";if(Array.isArray(t))return"array";return typeof t}function s(t,e){switch(e){case"integer":return typeof t==="number"&&Number.isInteger(t);case"number":return typeof t==="number"&&Number.isFinite(t);case"null":return t===null;case"array":return Array.isArray(t);case"object":return u(t)==="object";default:return typeof t===e}}function y(t,e,n,i){if(e.anyOf?.length){const f=e.anyOf.some(r=>{const o=[];y(t,r,n,o);return o.length===0});if(!f){const r=e.anyOf.map(o=>o.type??"?").join(" | ");i.push(`${n}: expected ${r}, got ${u(t)}`)}return}if(e.type&&!s(t,e.type)){i.push(`${n}: expected ${e.type}, got ${u(t)}`);return}if(e.enum&&!e.enum.includes(t)){i.push(`${n}: expected one of ${e.enum.map(f=>JSON.stringify(f)).join(", ")}, got ${JSON.stringify(t)}`);return}if(e.type==="array"&&Array.isArray(t)){if(e.minItems!==void 0&&t.length<e.minItems){i.push(`${n}: expected at least ${e.minItems} item(s), got ${t.length}`)}if(e.maxItems!==void 0&&t.length>e.maxItems){i.push(`${n}: expected at most ${e.maxItems} item(s), got ${t.length}`)}if(e.items){t.forEach((f,r)=>y(f,e.items,`${n}[${r}]`,i))}return}if(e.type==="object"&&u(t)==="object"){const f=t;for(const r of e.required??[]){if(f[r]===void 0)i.push(`${n}.${r}: required`)}if(e.properties){for(const[r,o]of Object.entries(e.properties)){if(f[r]!==void 0)y(f[r],o,`${n}.${r}`,i)}if(e.additionalProperties===false){const r=new Set(Object.keys(e.properties));for(const o of Object.keys(f)){if(!r.has(o))i.push(`${n}.${o}: unexpected property`)}}}}}export function validateParams(t,e){const n=[];const i=t===void 0||t===null?{}:t;y(i,e,"params",n);return{ok:n.length===0,errors:n}}export function applyDefaults(t,e){const n=u(t)==="object"?{...t}:{};for(const[i,f]of Object.entries(e.properties??{})){if(n[i]===void 0&&f.default!==void 0)n[i]=f.default}return n}