@spendgraph/tools 0.6.0 → 0.7.0

package/docs/stored.mdx

@@ -0,0 +1,83 @@
+export const meta = {
+  title: "A stored tool — spendgraph docs",
+  description:
+    "The dashboard owns the description, your code owns the arguments and the handler, and bindTool checks the two against each other before the model ever sees it.",
+};
+
+# A stored tool
+
+The description is the biggest lever on whether a model calls a tool correctly, and the part you will want to change most often. `bindTool` puts that half in the dashboard and leaves the rest in code.
+
+```ts
+import { bindTool } from "@spendgraph/tools";
+import { Spendgraph } from "@spendgraph/sdk";
+
+const lookup = await bindTool(sg, {
+  name: "lookup_contract",
+  args: [{ name: "ref", type: "string", required: true }] as const,
+  run: ({ ref }) => search(ref),
+});
+```
+
+No `description` in that call. That is the point — one source for the string the model reads, and it is the one you can edit without a release.
+
+## Who owns what
+
+```
+  DASHBOARD                        YOUR CODE
+  ─────────                        ─────────
+  description   ◀── iterate on     args      ──▶ run() is typed from them
+  effect            these without  run()     ──▶ the thing that actually happens
+  pinned            a deploy
+```
+
+Arguments stay in code because the handler's parameter types are inferred from them. Pull those from the server and every `run` is handed a `Record<string, unknown>`, which gives up the one guarantee [declaring a tool](/docs/tools/declaring) exists to provide.
+
+Write `as const` here exactly as you would for `tool()`. Without it inference falls back to nothing, and the drift check below becomes the only thing still catching a rename.
+
+## Drift fails at bind, not mid-loop
+
+The stored arguments and the declared ones are compared on the way through, by **name, type and requiredness** — the three a handler is written against.
+
+```ts
+import { ToolDriftError, ToolNotStoredError } from "@spendgraph/tools";
+
+try {
+  await bindTool(sg, spec);
+} catch (err) {
+  if (err instanceof ToolDriftError) err.differences;  // every disagreement, in words
+  if (err instanceof ToolNotStoredError) err.toolName; // nothing stored under that name
+}
+```
+
+`differences` reads like a review comment rather than a diff:
+
+```
+"ref" is string here and number stored
+"limit" is declared here but not stored
+"mode" is stored but not declared here
+```
+
+A description or a bound that differs is **not** drift — that is the dashboard being edited, which is the whole feature. A renamed argument is a handler about to be passed `undefined` halfway through an agent loop, so it throws.
+
+<Callout tone="warn" title="Bind at startup, not per request">
+  Every `bindTool` is a round trip to the API. Bind once when the process starts and hold the result, the same as you would a database connection — a bind inside a request handler puts a network hop in front of every model call.
+</Callout>
+
+<Callout tone="trap" title="A rename in the dashboard is a handler passed `undefined`">
+  The wording is editable without a deploy; the argument names are not. `bindTool` compares them at bind time and refuses — a deploy that fails is recoverable, and the same rename noticed mid-loop is a handler halfway through somebody's refund reading an argument that is not there.
+</Callout>
+
+## When nothing is stored yet
+
+`ToolNotStoredError` is the ordinary case of "you have not written this one in the dashboard yet", not an exotic failure. It exists so a 404 from three layers down arrives as a sentence naming the tool.
+
+Create the row first — `sg.tools.create` on the [client](/docs/sdk/client), or the Tools page in the dashboard — then bind to it.
+
+## It is an ordinary tool afterwards
+
+What comes back is what `tool()` returns. Register it on a bus, select it, invoke it, record it; nothing downstream knows or cares where the wording came from.
+
+```ts
+const bus = toolbus([lookup, calculate()]);
+```

package/docs/turns.mdx

@@ -0,0 +1,57 @@
+export const meta = {
+  title: "A turn — spendgraph docs",
+  description:
+    "A turn is selected once and remembers what it offered. Without that a record cannot tell 'chose not to' from 'was never offered', which are opposite bugs.",
+};
+
+# A turn
+
+```ts
+const turn = bus.trace(query);
+
+const reply = await llm.call(messages, { tools: turn });
+await turn.invoke(call.name, call.args);
+
+turn.record();   // { offeredTools, steps }
+```
+
+A turn is **selected once** and remembers what it offered. A trace cannot disagree with itself about what the model saw.
+
+## Offered is recorded, not just called
+
+Which tools were offered is recorded as well as which were called. Without it a record cannot tell **"chose not to"** from **"was never offered"** — which are opposite bugs, and look identical in a log that only lists calls.
+
+## What a turn answers
+
+| | |
+| --- | --- |
+| `turn.offered` | the shortlist this turn was given |
+| `turn.anthropic()` · `openai()` · `markdown()` | the same list, per provider |
+| `turn.effectOf(name)` | what that tool said it does, or `undefined` |
+| `turn.invoke(name, args)` | runs one and records the step. Never throws |
+| `turn.steps()` | the steps so far, in call order |
+| `turn.record()` | the pair, in the shape `report` takes |
+
+## Never throwing is the point
+
+A tool that fails is an **outcome the agent can react to** and a step worth recording, not an exception that ends the run — the same argument `status` and `error` exist on a rollout for.
+
+A tool the bus does not have is a failure that says what was offered, since the usual cause is a hallucinated name.
+
+<Callout tone="trap" title="`undefined` means two different things">
+  A tool that was offered and stayed quiet, and a tool this turn never offered, both answer `undefined`. `offeredTools` is what tells them apart — which is the difference between a model that declined to look something up and a model that could not.
+</Callout>
+
+## Usage drives the tiebreaker
+
+`bus.usage()` counts what has actually been called, which is what selection falls back on when a query singles out nothing. A call that never reached the tool — a name that does not exist, arguments that did not validate — is not counted, because it was not a use.
+
+## With a prompt
+
+```ts
+await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
+  tools: bus,
+});
+```
+
+The prompt hands the turn to your callback and puts `record()` on the rollout. The three packages compose without any of them importing another.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Declare a tool once, offer the right few, and record what was called.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,6 +28,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
     "./bogus": {
       "types": "./dist/bogus/index.d.ts",
       "import": "./dist/bogus/index.js"
@@ -36,6 +37,14 @@
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js"
     },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
     "./internals": {
       "types": "./dist/internals.d.ts",
       "import": "./dist/internals.js"
@@ -44,19 +53,18 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
-    "test": "npm run build && vitest run",
-    "examples": "npm run build && node examples/02-select/01-shortlist.mjs"
-  },
   "dependencies": {
-    "@spendgraph/sdk": "^0.6.0"
+    "@spendgraph/sdk": "^0.7.0",
+    "jszip": "^3.10.2",
+    "unpdf": "^1.8.1"
   },
   "devDependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/prompt": "^0.6.0",
+    "@spendgraph/prompt": "^0.7.0",
+    "pdf-lib": "^1.17.1",
     "typescript": "^5"
   },
   "engines": {
@@ -64,5 +72,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "vitest run",
+    "examples": "pnpm run build && node examples/02-select/01-shortlist.mjs"
   }
-}
+}

package/dist/builtin/deep-recall/deep-recall.js

@@ -1 +0,0 @@
-import{tool as s}from"../../tool/index.js";const o=20;function l(t){const a=t.maxFacts??o;return s({name:"deep_recall",description:"Searches your own knowledge base and returns an answer with the evidence it rests on. A walker follows linked contexts, so it answers questions spread across several notes \u2014 what do we know about X, what was decided and why. Ask one focused thing. Prefer it over a web search whenever the answer could already be in your records.",effect:"readonly",args:[{name:"question",type:"string",required:!0,maxLength:1e3,description:"One focused question, not a conversation and not several at once."},{name:"context_ids",type:"list",required:!1,description:"Contexts to start the walk from, as type:name \u2014 take them from the contexts of an earlier result. A hint, not a filter; the walk may go elsewhere."}],run:async({question:n,context_ids:r})=>{const e=await t.client.deepRecall({question:n,...t.graphId?{graphId:t.graphId}:{},...r?.length?{contextIds:r}:{}});return{summary:e.summary,facts:e.facts.slice(0,a),truncated:e.facts.length>a,contextsWalked:e.contexts_walked,coverage:e.coverage,fallback:e.fallback,costMicroUsd:Math.round(e.usage.cost_usd*1e6)}}})}export{l as deepRecall};

package/dist/builtin/write-document/commission.js

@@ -1,13 +0,0 @@
-import{createRequest as w,MoaApiError as h}from"./http.js";const T={queued:"pending",running:"running",succeeded:"done",failed:"failed",canceled:"failed"},M=["md","pdf","docx","pptx"],g=n=>{const t=n?.split(".").pop()?.toLowerCase();return t&&M.includes(t)?t:void 0};function E(n){if(!n?.length)return;const t=n.flatMap(e=>{const s=g(e.name);return!s||!(e.url||e.data)?[]:[{name:e.name??`document.${s}`,format:s,url:e.url,data:e.data,mime:e.contentType,sizeBytes:e.sizeBytes}]});return t.length?t:void 0}function I(n){return`
-
-<deliverables>
-Besides the text answer, save the finished deliverable into the artifacts/ directory of your working dir as: ${n.map(t=>`one .${t} file`).join(", ")}.
-</deliverables>`}function x(n){let t=n.task;return n.context&&(t+=`
-
-<context>
-${n.context}
-</context>`),n.design&&(t+=`
-
-<design>
-${n.design}
-</design>`),n.artifacts?.length&&(t+=I(n.artifacts)),t}function _(n={}){const t=w(n);return{async create(e){const s=await t("/tasks",{method:"POST",body:{task:x(e),mode:"striker",...e.sessionId?{sessionId:e.sessionId}:{},...e.newSessionId?{newSessionId:e.newSessionId}:{}}});if(!s.id)throw new h("Moa did not return a task id",502);return s.id},async get(e,s){const c=s?.waitMs&&s.waitMs>0?`?waitMs=${Math.floor(s.waitMs)}`:"",o=await t(`/tasks/${encodeURIComponent(e)}${c}`,{signal:s?.signal}),i=o.status?T[o.status]:void 0;return{id:o.id??e,status:i??"running",output:o.result,error:o.error,costUsd:o.costUsd,numTurns:o.numTurns,sessionId:o.sessionId,artifacts:E(o.artifacts)}},async cancel(e){await t(`/tasks/${encodeURIComponent(e)}`,{method:"DELETE"})}}}const b=3e4,A=2e3,k=3,y=25e3;class m extends Error{commissionId;constructor(t){super(`Commission ${t} was cancelled by the caller.`),this.name="CommissionAbortedError",this.commissionId=t}}class C extends Error{commissionId;timeoutMs;constructor(t,e){super(`Commission ${t} did not complete within ${e/1e3}s. The task may still be running in the background.`),this.name="CommissionTimeoutError",this.commissionId=t,this.timeoutMs=e}}const f=(n,t)=>new Promise(e=>{const s=()=>e();t?.addEventListener("abort",s,{once:!0}),setTimeout(()=>{t?.removeEventListener("abort",s),e()},n)});async function p(n,t,e={}){const s=e.timeoutMs??b,c=e.pollIntervalMs??A,o=e.settleMs??0,i=e.signal,l=Date.now()+s;for(;;){if(i?.aborted)throw new m(t);const u=l-Date.now();if(u<=0)throw new C(t,s);let r;try{r=await n.get(t,{waitMs:Math.min(u,y),signal:i})}catch(d){throw i?.aborted?new m(t):d}if(r.status==="failed")return r;if(r.status==="done"){const d=a=>!a.output?.trim()||e.expectArtifacts===!0&&!a.artifacts?.length;for(let a=0;o>0&&a<k&&d(r);a++)await f(o),r=await n.get(t);return r}await f(Math.min(c,Math.max(0,l-Date.now())),i)}}export{m as CommissionAbortedError,C as CommissionTimeoutError,b as INTERACTIVE_TIMEOUT_MS,_ as createCommissionClient,p as pollUntilDone};

package/dist/builtin/write-document/index.d.ts

@@ -1,6 +0,0 @@
-export type { CommissionClient, PollOptions } from "./commission.js";
-export { CommissionAbortedError, CommissionTimeoutError, createCommissionClient, INTERACTIVE_TIMEOUT_MS, pollUntilDone, } from "./commission.js";
-export { DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign } from "./design.js";
-export { MOA_BASE_URL, MoaApiError, type MoaClientConfig } from "./http.js";
-export type { ArtifactFormat, CommissionArtifact, CommissionInput, CommissionResult, CommissionStatus, } from "./types.js";
-export { type WriteDocumentOptions, writeDocument } from "./write-document.js";

package/dist/builtin/write-document/index.js

@@ -1 +0,0 @@
-import{CommissionAbortedError as e,CommissionTimeoutError as i,createCommissionClient as m,INTERACTIVE_TIMEOUT_MS as t,pollUntilDone as n}from"./commission.js";import{DEFAULT_DESIGN as s,mergeDesign as p,renderDesign as A}from"./design.js";import{MOA_BASE_URL as T,MoaApiError as C}from"./http.js";import{writeDocument as f}from"./write-document.js";export{e as CommissionAbortedError,i as CommissionTimeoutError,s as DEFAULT_DESIGN,t as INTERACTIVE_TIMEOUT_MS,T as MOA_BASE_URL,C as MoaApiError,m as createCommissionClient,p as mergeDesign,n as pollUntilDone,A as renderDesign,f as writeDocument};

package/dist/builtin/write-document/write-document.js

@@ -1 +0,0 @@
-import{tool as f}from"../../tool/index.js";import{CommissionAbortedError as l,CommissionTimeoutError as h,createCommissionClient as g,pollUntilDone as p}from"./commission.js";import{DEFAULT_DESIGN as w,mergeDesign as y,renderDesign as _}from"./design.js";const x=["pdf","pptx","docx","md"],b=6e5,M=2e3,U=4e3;function v(e,i){return`Commissions a document agent to write and render a finished file \u2014 ${e.map(t=>`.${t}`).join(", ")} \u2014 and hands back where to download it. Use it when the answer has to be a document somebody opens: a report, a deck, a proposal, a one-pager. Not for text you can simply write in your reply. It runs for minutes and it costs money, so brief it once and brief it fully \u2014 the agent cannot see this conversation, so every fact, figure and quote it must use goes in \`source\`. Design is already settled by ${i.name??"the house style"}; use \`design_notes\` only for what this one document must do differently.`}function E(e,i,t,d){const r=(e.artifacts??[]).map(o=>({name:o.name,format:o.format,url:o.url,mime:o.mime,sizeBytes:o.sizeBytes,...d&&o.data?{data:o.data}:{}}));return{taskId:e.id,sessionId:e.sessionId,status:"done",style:i,documents:r,delivered:r.length>0,writeUp:e.output?.slice(0,t),truncated:(e.output?.length??0)>t,turns:e.numTurns,costMicroUsd:e.costUsd===void 0?void 0:Math.round(e.costUsd*1e6)}}function T(e,i,t){return{taskId:e,status:"running",style:i,documents:[],delivered:!1,note:`Still rendering after ${Math.round(t.timeoutMs/1e3)}s. The task is not lost \u2014 say so rather than commissioning it again.`}}function L(e){if(!e.client&&!e.apiKey?.trim())throw new Error("writeDocument needs a Moa apiKey; it will not read one from the process.");const i=e.formats?.length?e.formats:x,t=y(w,e.design),d=e.maxChars??U,r=e.client??g({apiKey:e.apiKey,baseUrl:e.baseUrl,...e.fetch?{fetch:e.fetch}:{}});return f({name:"write_document",description:v(i,t),effect:"destructive",args:[{name:"brief",type:"text",required:!0,maxLength:8e3,description:"What to produce, who reads it, what it must cover and how long it runs. Write it as you would brief a person who knows the craft and nothing about this account."},{name:"format",type:"enum",required:!0,options:["pdf","pptx","docx","md"],description:"pptx for anything presented, pdf for anything sent, docx for anything edited."},{name:"source",type:"text",required:!1,maxLength:4e4,description:"The material it must build from \u2014 figures, findings, quotes, an outline \u2014 verbatim. Anything missing here the agent will either omit or invent."},{name:"design_notes",type:"text",required:!1,maxLength:2e3,description:"How this one document departs from the house style, in plain words. Leave it empty unless the user asked for something specific."},{name:"session_id",type:"string",required:!1,description:"Continue an earlier write_document instead of starting over \u2014 take it from that result's sessionId. Use it to revise a document or to recast one into another format."}],run:async({brief:o,format:s,source:u,design_notes:m,session_id:c})=>{if(!i.includes(s))throw new Error(`write_document was asked for .${s}, which this deployment does not produce (${i.map(n=>`.${n}`).join(", ")}).`);const a=await r.create({task:o,context:u,design:_(t,s,m),artifacts:[s],...c?{sessionId:c}:{}});try{const n=await p(r,a,{timeoutMs:e.timeoutMs??b,settleMs:M,expectArtifacts:!0,...e.signal?{signal:e.signal}:{}});if(n.status==="failed")throw new Error(`write_document: Moa task ${a} failed: ${n.error??"no reason given"}`);return E(n,t.name,d,e.includeData===!0)}catch(n){if(n instanceof l&&e.cancelOnAbort!==!1&&await r.cancel?.(a).catch(()=>{}),n instanceof h)return T(a,t.name,n);throw n}}})}export{L as writeDocument};