@spendgraph/tools 0.7.0 → 0.8.0

package/dist/search/search.d.ts

@@ -14,6 +14,10 @@ export interface SearchUsage {
     reasoningTokens: number;
     searchQueries: number;
 }
+export interface SearchFailure {
+    source: string;
+    reason: string;
+}
 /** What every searcher hands back, whoever did the searching. */
 export interface Searched {
     answer: string;
@@ -21,6 +25,7 @@ export interface Searched {
     model: string;
     truncated: boolean;
     usage: SearchUsage;
+    failed?: SearchFailure[];
 }
 export interface SearchAsk {
     query: string;
@@ -29,6 +34,7 @@ export interface SearchAsk {
 }
 export type Searcher = ((ask: SearchAsk) => Promise<Searched>) & {
     domains?: readonly string[];
+    source?: string;
 };
 /** What every searcher is configured with; each adds only where its answers come from. */
 export interface SearcherOptions {

package/dist/search/searxng/searxng.js

@@ -1,5 +1,5 @@
-import{checkUrl as S}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as x}from"../search.js";import{textOf as A}from"./text.js";const T="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
+import{checkUrl as x}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as A}from"../search.js";import{textOf as T}from"./text.js";const f="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
 ${t.url}
-${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,f=t.pageChars??X,b={...H,...t.pages},O=y(t);async function d(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>d(a,s)))]}async function p(n){const s=AbortSignal.timeout(u);let e=S(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=S(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await p(n.url);if(!s.ok)return n.snippet;const e=A((await s.text()).slice(0,L));return e?e.slice(0,f):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await p(n);return s.ok&&A((await s.text()).slice(0,L)).slice(0,f)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:T,truncated:s.length>g,usage:{...x,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await d(n,e),l=s==="deep"?await P(o,e):[o],w=z(l),m=w.slice(0,h),_=m.slice(0,b[s]),k=await Promise.all(_.map(M)),E=_.map(($,j)=>K($,k[j])).join(`
+${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,d=t.pageChars??X,b={...H,...t.pages},O=y(t);async function p(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>p(a,s)))]}async function w(n){const s=AbortSignal.timeout(u);let e=x(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=x(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await w(n.url);if(!s.ok)return n.snippet;const e=T((await s.text()).slice(0,L));return e?e.slice(0,d):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await w(n);return s.ok&&T((await s.text()).slice(0,L)).slice(0,d)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:f,truncated:s.length>g,usage:{...A,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await p(n,e),l=s==="deep"?await P(o,e):[o],_=z(l),m=_.slice(0,h),E=m.slice(0,b[s]),k=await Promise.all(E.map(M)),S=E.map(($,j)=>K($,k[j])).join(`
 
-`);return{answer:E.slice(0,g),results:m.map(q),model:T,truncated:E.length>g||w.length>m.length,usage:{...x,searchQueries:l.length}}},t.domains?.length?{domains:[...t.domains]}:{})}export{tt as searxng};
+`);return{answer:S.slice(0,g),results:m.map(q),model:f,truncated:S.length>g||_.length>m.length,usage:{...A,searchQueries:l.length}}},{source:f,...t.domains?.length?{domains:[...t.domains]}:{}})}export{tt as searxng};

package/dist/search/sonar/sonar.js

@@ -1 +1 @@
-import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="https://api.perplexity.ai/chat/completions",p=6e4,T=3e5,u=500;function A(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),a=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:p),t=await a(()=>i(f,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,u);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},e.domains?.length?{domains:[...e.domains]}:{})}export{A as sonar};
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="sonar",p="https://api.perplexity.ai/chat/completions",u=6e4,T=3e5,y=500;function O(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const a=e.fetch??globalThis.fetch.bind(globalThis),i=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:u),t=await i(()=>a(p,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,y);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},{source:f,...e.domains?.length?{domains:[...e.domains]}:{}})}export{O as sonar};

package/dist/search/tavily/tavily.js

@@ -1 +1 @@
-import{retrying as l}from"../retry.js";import{DEFAULT_MAX_CHARS as m,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const u="https://api.tavily.com/search",y="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),r=l(e);return Object.assign(async({query:s,depth:o,recency:t})=>{const{search_depth:c,pages:d}=T[o],a=await r(()=>i(u,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:s,search_depth:c,include_answer:!0,include_raw_content:!0,max_results:Math.min(d,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const h=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${h}`)}return _(await a.json(),y,e.maxChars??m,e.maxResults??n)},e.domains?.length?{domains:[...e.domains]}:{})}export{S as tavily};
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as u,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const y="https://api.tavily.com/search",i="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const r=e.fetch??globalThis.fetch.bind(globalThis),s=m(e);return Object.assign(async({query:o,depth:c,recency:t})=>{const{search_depth:d,pages:h}=T[c],a=await s(()=>r(y,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:o,search_depth:d,include_answer:!0,include_raw_content:!0,max_results:Math.min(h,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const l=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${l}`)}return _(await a.json(),i,e.maxChars??u,e.maxResults??n)},{source:i,...e.domains?.length?{domains:[...e.domains]}:{}})}export{S as tavily};

package/dist/tool/tool.d.ts

@@ -9,6 +9,10 @@ export interface ToolSpec<T extends readonly ArgSpec[]> {
     trust?: Trust;
     costOf?(value: unknown): number | undefined;
     needs?: readonly string[];
+    wants?: {
+        name: string;
+        description: string;
+    };
     run(args: ArgsOf<T>): Promise<unknown> | unknown;
 }
 /**

package/dist/tool/tool.js

@@ -1 +1 @@
-const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"],a=["own","external"];function s(n,t){if(!t.options?.length)throw new Error(`Tool "${n}" argument "${t.name}" is an enum with no options, so nothing can satisfy it.`);const e=new Set;for(const o of t.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${t.name}" has a blank option, which the model can pick and you cannot act on.`);if(e.has(o))throw new Error(`Tool "${n}" argument "${t.name}" lists "${o}" twice.`);e.add(o)}}function f(n,t){if(t){for(const e of t)if(!e.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function h(n,t){const e=new Set;for(const o of t){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(e.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);e.add(o.name),o.type==="enum"&&s(n,o)}}function d(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(h(n.name,n.args),f(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);if(n.trust!==void 0&&!a.includes(n.trust))throw new Error(`Tool "${n.name}" declares trust "${n.trust}", which is not one of ${a.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(t=>({...t,options:t.options?[...t.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},...n.trust?{trust:n.trust}:{},...n.costOf?{costOf:n.costOf}:{},...n.needs?.length?{needs:[...n.needs]}:{},run:n.run}}export{d as tool};
+const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"],a=["own","external"];function s(n,t){if(!t.options?.length)throw new Error(`Tool "${n}" argument "${t.name}" is an enum with no options, so nothing can satisfy it.`);const e=new Set;for(const o of t.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${t.name}" has a blank option, which the model can pick and you cannot act on.`);if(e.has(o))throw new Error(`Tool "${n}" argument "${t.name}" lists "${o}" twice.`);e.add(o)}}function f(n,t){if(t){for(const e of t)if(!e.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function h(n,t){const e=new Set;for(const o of t){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(e.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);e.add(o.name),o.type==="enum"&&s(n,o)}}function d(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(h(n.name,n.args),f(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);if(n.trust!==void 0&&!a.includes(n.trust))throw new Error(`Tool "${n.name}" declares trust "${n.trust}", which is not one of ${a.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(t=>({...t,options:t.options?[...t.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},...n.trust?{trust:n.trust}:{},...n.costOf?{costOf:n.costOf}:{},...n.needs?.length?{needs:[...n.needs]}:{},...n.wants?{wants:{...n.wants}}:{},run:n.run}}export{d as tool};

package/dist/types/tool.d.ts

@@ -106,6 +106,19 @@ export interface Tool<Args = Record<string, unknown>> {
      * where the words a caller actually types are declared.
      */
     aliases?: string[];
+    /**
+     * A second, differently-shaped input the tool would rather be given, named.
+     *
+     * A stage hands every tool the one question it wrote. That suits a search
+     * engine and defeats a catalogue that matches on a title: measured against
+     * OpenAlex, a 280-character sub-question found nothing where the same ask as
+     * an 80-character phrase found ten papers. Declaring it here is what lets the
+     * stage be told to write one, without the stored wording naming any tool.
+     */
+    wants?: {
+        name: string;
+        description: string;
+    };
     /**
      * Offered whatever selection decides — an escalation path, a refusal, where
      * losing a similarity search is not an acceptable outcome.

package/docs/builtins.mdx

@@ -36,11 +36,10 @@ const bus = toolbus([
 | `httpRequest()` | a GET or POST to hosts you named | local |
 | `extract()` | the text of a file at a URL — pdf, docx, a page, md, txt | local |
 | `codeExec()` | a short program, run wherever you say | sandbox |
-| `writeDocument()` | a document agent that returns a rendered file | key |
 | `publish()` | content out as a file at a public URL, through the app | key |
 | `webSearch()` | a searched answer with its sources, from a searcher you pick | local or key |
 | `wikidata()` | what Wikidata records about a thing, as text with every id named | local |
-| `openalex()` | papers on a topic, as text with a DOI and a PDF where one is open | local |
+| `paperSearch()` | published papers on a topic, as text with a DOI and a PDF where one is open, from a paper searcher you pick | local or key |
 | `recall()` | what your memory holds about something, one note per row | key |
 | `deepRecall()` | the same, walked across linked notes, with the evidence | key |
 | `remember()` | one thing filed under a `type:name` context | key |
@@ -126,7 +125,66 @@ webSearch({ search: sonar({ apiKey, domains: ["gov.uk"] }), maxDepth: "pro" });
 webSearch({ search: searxng({ baseUrl: "http://localhost:8080", language: "en" }), maxDepth: "deep" });
 ```
 
-Both hand back the same shape — `answer`, `results`, `model`, `truncated`, `usage` — so whatever reads one reads the other; only where the answer came from and what it cost differ. The model chooses `query`, `depth` and `recency`; `domains`, engines and language are pinned on the searcher, so it cannot widen them. Pages the SearXNG searcher reads go through the same guard as `httpRequest`, so a private address is refused even when an engine offered it. A stock SearXNG answers the json format with a 403 until `settings.yml` lists it under `search.formats` and the limiter is off, and the error says so. `examples/search` runs both searchers directly.
+Both hand back the same shape — `answer`, `results`, `model`, `truncated`, `usage` — so whatever reads one reads the other; only where the answer came from and what it cost differ. `everySearch([sonar, tavily, searxng])` is that shape used on itself: one searcher over several, asked at the same time. The model chooses `query`, `depth` and `recency`; `domains`, engines and language are pinned on the searcher, so it cannot widen them. Pages the SearXNG searcher reads go through the same guard as `httpRequest`, so a private address is refused even when an engine offered it. A stock SearXNG answers the json format with a 403 until `settings.yml` lists it under `search.formats` and the limiter is off, and the error says so. `examples/search` runs both searchers directly.
+
+**`paperSearch`** is `webSearch` for the literature, and ships three searchers. `openAlexPapers` is [OpenAlex](https://openalex.org), free and keyless. `semanticScholar` is the [Semantic Scholar](https://www.semanticscholar.org/product/api) graph, and carries the `tldr` as each paper's takeaway. `consensus` is [Consensus](https://consensus.app), which needs a key and is the only one that says how a study was run — `rct`, `meta-analysis` — with its sample size and a one-line finding.
+
+Keys, and what each is worth:
+
+| | |
+| --- | --- |
+| `openAlexPapers` | optional, free, from [OpenAlex authentication](https://help.openalex.org/api/authentication/) — sent as a bearer token, never in the url. Basic use is keyless; a key is ten times the daily budget, and heavier use is pay as you go |
+| `semanticScholar` | optional, free, from [the API key form](https://www.semanticscholar.org/product/api#api-key-form) — emailed after review, so not the same day. Keyless is 1000 req/s *shared with every unauthenticated caller on the internet*, which in practice means routine 429s; a key is 1 req/s that is yours |
+| `consensus` | required, from a [Consensus](https://consensus.app) account |
+
+A 429 from the keyless Semantic Scholar pool is not a failure to design around — under `everyPaper` it is one source that did not answer while the others did.
+
+**What a search cost** rides back with it. OpenAlex prices every call in its own envelope — `meta.cost_usd` — and that becomes `costMicroUsd` on the `PapersFound`, in micro-USD like every other price here. A source that does not price its own calls takes `costMicroUsd` as an option instead, which is what your plan charges per search:
+
+```ts
+everyPaper([openAlexPapers({ apiKey }), consensus({ apiKey, costMicroUsd: 2500 })]);
+```
+
+`everyPaper` sums what the sources that answered reported, and bills nothing for one that failed. `paper_search` declares `costOf`, so the number lands on the result as `costMicros` and `spentOn([...results])` adds a run up. Only sources that said are counted: a search with no price is unmeasured, not free, and those are different claims.
+
+The tool returns `{ answer, results, costMicroUsd }` rather than a bare string. The model still reads only `answer` — `render()` has always unwrapped that shape — while `results` become the result's `sources`, one per paper, preferring an open PDF, then the source's own page, then `https://doi.org/…`.
+
+```ts
+import { paperSearch } from "@spendgraph/tools";
+import { consensus, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
+
+paperSearch({ papers: openAlexPapers({ apiKey }) });
+paperSearch({ papers: semanticScholar({ apiKey, fieldsOfStudy: ["Medicine"] }), maxResults: 5 });
+paperSearch({ papers: consensus({ apiKey, studyTypes: ["rct"], excludePreprints: true }) });
+```
+
+All three hand back the same `Paper` — title, year, authors, venue, citations, DOI, an open PDF, a study type and sample size where the source knows them, a takeaway, and the abstract — so whatever reads one reads the others. The model chooses `query`, `year_min`, `year_max`, `min_citations` and `open_access`; the study filters, fields of study and journals are pinned on the searcher, so it cannot widen them. `openalex()` is the preset for the keyless case, and is `paperSearch({ papers: openAlexPapers(opts) })` with nothing added.
+
+**Two or three sources at once** is `everySearch` in `@spendgraph/tools/search` and `everyPaper` in `@spendgraph/tools/papers`. Each takes a list, returns one searcher of the same type, and asks all of them at the same time.
+
+```ts
+import { paperSearch, webSearch } from "@spendgraph/tools";
+import { consensus, everyPaper, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
+import { everySearch, searxng, sonar } from "@spendgraph/tools/search";
+
+paperSearch({ papers: everyPaper([consensus({ apiKey }), semanticScholar(), openAlexPapers()]) });
+webSearch({ search: everySearch([sonar({ apiKey }), searxng({ baseUrl })]) });
+```
+
+One tool, not three. `busgroup` is the other way to hold several providers — a bus each, `namespace: true`, and the model sees `consensus__paper_search` beside `s2__paper_search` — and it is the right shape when the buses do *different* things, because a name there has to say which one runs. These do the same thing: same ask in, same shape out. Interchangeable by construction is a fan-out, not a routing decision the model has any basis to make, and three namespaced copies spend three shortlist slots on one capability.
+
+What the merge does with what comes back:
+
+| | |
+| --- | --- |
+| order | round-robin — first from each source, then second from each, so no one corpus owns the top |
+| the same paper twice | folded on DOI, else on the title with punctuation and case removed |
+| a fold | fills gaps rather than dropping one: Consensus' `studyType` survives alongside Semantic Scholar's abstract, and the higher citation count wins |
+| a source that fails | named in `failed`, and the rest still answer; `paper_search` prints `openalex did not answer: …` under the list |
+| every source failing | the call fails, quoting what each one said |
+| the bill | three providers per call, not one — a fan-out costs what its parts cost |
+
+`everySearch` puts each answer under `# via <model>` so a quote stays attributable — `via` because a page's own text routinely carries an `#` heading of its own, and the marker has to be the one line that cannot be mistaken for content, unions the links, and sums all five token lines. It keeps `domains` only when *every* searcher is pinned, since one unpinned searcher means the answer is no longer restricted.
 
 **`codeExec`** runs a short program and hands back what it printed — for work an arithmetic expression cannot state: sorting, filtering, joining, parsing. It takes a **required** `sandbox` and has no default, because a default would mean running model-written code in the process that called it. That is what `calculate` exists to avoid, and shipping one here would undo it.
 
@@ -151,6 +209,9 @@ codeExec({ sandbox, language: "python", timeoutMs: 10_000 });
 
 Anything satisfying `execute` works — a hosted sandbox, a container, a WASM runtime. A failed run comes back with `ok: false` rather than throwing, so the model reads `stderr` and corrects its own code instead of getting an opaque tool failure.
 
-**`writeDocument`** commissions a document from an agent and hands back a rendered file. It takes a `MoaClient` — `create`, `get`, and optionally `cancel` — so the queue it talks to is yours. Long jobs are the normal case, which is why there are two errors rather than one: `MoaTimeoutError` when the wait ran out with work still going, and `MoaAbortedError` when something cancelled it. `DEFAULT_DESIGN`, `mergeDesign` and `renderDesign` are how the house style reaches the agent without being retyped per call.
+Commissioning a document agent used to live here as `writeDocument`. It now lives in
+`@spendgraph/vigil/agents` as `moaAgent()`, because the work takes minutes and a tool has to
+return now: a run parks on the agent and picks itself back up, rather than holding a process
+open for ten minutes.
 
 **`httpRequest`** takes a **required** allowlist and has no default. It is https only, refuses private, loopback, link-local and `.internal`/`.local` hosts **even if you list them**, and sets headers itself so a credential is never something the model can redirect. If the guard feels heavy, that is the correct amount of heavy: this is the one builtin that can exfiltrate. `allow: ["*"]` opens it to every public host, for the one case where the tool is a reader of the open web rather than a client of your own APIs; the private-address and https refusals still hold.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Declare a tool once, offer the right few, and record what was called.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,6 +37,10 @@
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js"
     },
+    "./papers": {
+      "types": "./dist/papers/index.d.ts",
+      "import": "./dist/papers/index.js"
+    },
     "./search": {
       "types": "./dist/search/index.d.ts",
       "import": "./dist/search/index.js"
@@ -57,13 +61,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/sdk": "^0.7.0",
+    "@spendgraph/sdk": "^0.8.0",
     "jszip": "^3.10.2",
     "unpdf": "^1.8.1"
   },
   "devDependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/prompt": "^0.7.0",
+    "@spendgraph/config": "0.8.0",
+    "@spendgraph/prompt": "^0.8.0",
     "pdf-lib": "^1.17.1",
     "typescript": "^5"
   },
@@ -75,7 +80,8 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "examples": "pnpm run build && node examples/02-select/01-shortlist.mjs",
     "test": "vitest run",
-    "examples": "pnpm run build && node examples/02-select/01-shortlist.mjs"
+    "typecheck": "tsc -p tsconfig.tests.json"
   }
 }

package/dist/agents/index.d.ts

@@ -1 +0,0 @@
-export { type ArtifactFormat, DEFAULT_DESIGN, type DesignGuide, MoaAbortedError, type MoaClient, MoaTimeoutError, mergeDesign, renderDesign, type WriteDocumentOptions, writeDocument, } from "./moa/index.js";

package/dist/agents/index.js

@@ -1 +0,0 @@
-import{DEFAULT_DESIGN as o,MoaAbortedError as t,MoaTimeoutError as D,mergeDesign as i,renderDesign as m,writeDocument as n}from"./moa/index.js";export{o as DEFAULT_DESIGN,t as MoaAbortedError,D as MoaTimeoutError,i as mergeDesign,m as renderDesign,n as writeDocument};

package/dist/agents/moa/design.d.ts

@@ -1,49 +0,0 @@
-import type { ArtifactFormat } from "./types.js";
-/**
- * The house style a commissioned document is built to.
- *
- * Every field is optional because a caller overrides only what its brand
- * actually fixes; the rest falls back to {@link DEFAULT_DESIGN}.
- */
-export interface DesignGuide {
-    /** What the style is called, so the document can say which one it followed. */
-    name?: string;
-    fonts?: {
-        heading?: string;
-        body?: string;
-        mono?: string;
-    };
-    palette?: {
-        primary?: string;
-        accent?: string;
-        text?: string;
-        muted?: string;
-        surface?: string;
-    };
-    /** Page size, margins, grid, density. */
-    layout?: string;
-    /** How a figure earns its place and what it may not do. */
-    charts?: string;
-    /** How the writing sounds. */
-    tone?: string;
-    /** Fetchable logo, dropped on the cover and nowhere else. */
-    logoUrl?: string;
-    /** Hard rules, appended to the defaults rather than replacing them. */
-    rules?: readonly string[];
-}
-/**
- * What a document looks like when nobody has said.
- *
- * Chosen to be defensible rather than distinctive: one typeface, one accent,
- * real whitespace, and figures that carry a single message.
- */
-export declare const DEFAULT_DESIGN: DesignGuide;
-/**
- * A caller's guide over the defaults: named fields win, `rules` accumulate.
- *
- * Rules append because they are constraints — a brand adding "never use red"
- * means it as well as the defaults, not instead of them.
- */
-export declare function mergeDesign(base: DesignGuide, over?: DesignGuide): DesignGuide;
-/** The guide as the block Moa reads, since its artifact pipeline is prompt-driven. */
-export declare function renderDesign(guide: DesignGuide, format: ArtifactFormat, notes?: string): string;

package/dist/agents/moa/design.js

@@ -1,5 +0,0 @@
-const c={name:"Spendgraph house style",fonts:{heading:"Inter",body:"Inter",mono:"JetBrains Mono"},palette:{primary:"#0F172A",accent:"#2563EB",text:"#111827",muted:"#64748B",surface:"#FFFFFF"},layout:"A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, and one heading scale used consistently (28/20/16/12). Whitespace is the design.",charts:"One message per figure, stated in its caption. Label series directly where there are three or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three slices, and axes that start at zero unless the caption says why not.",tone:"Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no throat-clearing, no sentence that survives being deleted.",rules:["A cover carrying the title, date and author, and no other ornament.","Every number traceable to something in the source material; invent nothing.","Tables for anything being compared; prose for anything being argued.","No stock imagery, no clip art, no placeholder text in the finished file.","Page numbers on every page after the cover."]},d={pdf:"Cover, then contents if it runs past four pages, then the body. Figures captioned and referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",pptx:"16:9. One idea per slide, and the title is that idea as a sentence \u2014 a claim, not a label. At most six lines of body per slide, one figure per slide at most, and everything you cut goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",docx:"Real Word styles for headings rather than manual bold, a table-of-contents field rather than a typed list, a header row on every table, and captions on figures.",md:"A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML."};function i(e,t){return e?t?{...e,...t}:e:t}function h(e,t){return t?{...e,...t,fonts:i(e.fonts,t.fonts),palette:i(e.palette,t.palette),rules:[...e.rules??[],...t.rules??[]]}:e}const a=(e,t)=>t?[`${e}: ${t}`]:[];function p(e,t,o){const{fonts:r,palette:n}=e;return[...a("Style",e.name),...a("Typefaces",[r?.heading&&`headings ${r.heading}`,r?.body&&`body ${r.body}`,r?.mono&&`code ${r.mono}`].filter(Boolean).join(", ")||void 0),...a("Palette",[n?.primary&&`primary ${n.primary}`,n?.accent&&`accent ${n.accent}`,n?.text&&`text ${n.text}`,n?.muted&&`muted ${n.muted}`,n?.surface&&`surface ${n.surface}`].filter(Boolean).join(", ")||void 0),...a("Layout",e.layout),...a("Figures",e.charts),...a("Voice",e.tone),...a("Logo",e.logoUrl),`Format craft (.${t}): ${d[t]}`,...e.rules?.length?[`Rules:
-${e.rules.map(s=>`- ${s}`).join(`
-`)}`]:[],...o?.trim()?[`Overrides for this document, which win over everything above:
-${o.trim()}`]:[]].join(`
-`)}export{c as DEFAULT_DESIGN,h as mergeDesign,p as renderDesign};

package/dist/agents/moa/http.d.ts

@@ -1,34 +0,0 @@
-/** Anything shaped like an `AbortSignal`, so a Worker's own signal fits too. */
-export interface AbortSignalLike {
-    readonly aborted: boolean;
-    addEventListener(type: "abort", listener: () => void, opts?: {
-        once?: boolean;
-    }): void;
-    removeEventListener(type: "abort", listener: () => void): void;
-}
-/** Where Moa lives, unless a config says otherwise. */
-export declare const MOA_BASE_URL = "https://api.fnmoa.com";
-export interface MoaClientConfig {
-    /** Read from here rather than the environment, as every other builtin does. */
-    apiKey?: string;
-    baseUrl?: string;
-    /** Ceiling on one HTTP call, not on the commission. Default 60000. */
-    timeoutMs?: number;
-    /** Injected for tests. */
-    fetch?: typeof fetch;
-}
-/** A non-2xx from Moa, carrying the status so a caller can tell 4xx from 5xx. */
-export declare class MoaApiError extends Error {
-    readonly status: number;
-    readonly detail?: string;
-    constructor(message: string, status: number, detail?: string);
-}
-interface RequestOptions {
-    method?: string;
-    body?: unknown;
-    signal?: AbortSignalLike;
-    timeoutMs?: number;
-}
-/** One `request<T>(path, opts)` against Moa, with auth, timeout and error shape settled. */
-export declare function createRequest(config?: MoaClientConfig): <T>(path: string, opts?: RequestOptions) => Promise<T>;
-export {};

package/dist/agents/moa/http.js

@@ -1 +0,0 @@
-const f="https://api.fnmoa.com",M=6e4,_=500;class c extends Error{status;detail;constructor(t,s,n){super(n?`${t}: ${n}`:t),this.name="MoaApiError",this.status=s,this.detail=n}}function T(e){const t=e.cause;return t?.code??t?.message??e.message}function m(e,t){const s=new AbortController,n=()=>s.abort();let r=!1;const o=setTimeout(()=>{r=!0,n()},e);return t?.addEventListener("abort",n,{once:!0}),t?.aborted&&n(),{signal:s.signal,expired:()=>r,release:()=>{clearTimeout(o),t?.removeEventListener("abort",n)}}}function $(e={}){const t=e.fetch??globalThis.fetch.bind(globalThis),s=(e.baseUrl??f).replace(/\/+$/,"");return async function(r,o={}){const u=o.timeoutMs??e.timeoutMs??6e4,i=o.method??"GET",d=`${s}${r}`,{signal:E,expired:h,release:b}=m(u,o.signal);try{const a=await t(d,{method:i,signal:E,headers:{...e.apiKey?{authorization:`Bearer ${e.apiKey}`}:{},...o.body===void 0?{}:{"content-type":"application/json"}},...o.body===void 0?{}:{body:JSON.stringify(o.body)}}).catch(l=>{throw o.signal?.aborted?l:h()?new c(`Moa did not answer ${i} ${r}`,504,`${u}ms`):new c(`Moa is unreachable at ${d}`,0,T(l))});if(!a.ok)throw new c(`Moa returned ${a.status} for ${i} ${r}`,a.status,(await a.text()).slice(0,500));return a.status===204?void 0:await a.json()}finally{b()}}}export{f as MOA_BASE_URL,c as MoaApiError,$ as createRequest};

package/dist/agents/moa/index.d.ts

@@ -1,74 +0,0 @@
-import { type DesignGuide } from "./design.js";
-import type { AbortSignalLike } from "./http.js";
-import { type MoaClient } from "./moa.js";
-import type { ArtifactFormat } from "./types.js";
-export interface WriteDocumentOptions {
-    /** Moa key. Required, and read from here rather than the environment. */
-    apiKey: string;
-    /** Defaults to `https://api.fnmoa.com`. */
-    baseUrl?: string;
-    /**
-     * House style laid over {@link DEFAULT_DESIGN}: named fields win, `rules`
-     * accumulate. This is where a brand goes, so the model cannot dilute it.
-     */
-    design?: DesignGuide;
-    /** Formats this deployment will produce. Default all four. */
-    formats?: readonly ArtifactFormat[];
-    /** Give up waiting after this. Default 600000 — rendering is minutes, not seconds. */
-    timeoutMs?: number;
-    /** Stops the wait. With `cancelOnAbort`, stops the task too. */
-    signal?: AbortSignalLike;
-    /** Cancel the task server-side when `signal` fires. Default true. */
-    cancelOnAbort?: boolean;
-    /** Return artifact bytes inline. Default false: base64 of a PDF is not context. */
-    includeData?: boolean;
-    /** Longest write-up handed back. Default 4000 characters. */
-    maxChars?: number;
-    /** Injected for tests, and for anyone fronting Moa with their own transport. */
-    client?: MoaClient;
-    /** Injected for tests. */
-    fetch?: typeof fetch;
-}
-/**
- * A document agent, briefed in your house style.
- *
- * Style is the deployment's business and content is the model's: the guide
- * comes from `options.design`, and `design_notes` may bend it for one document
- * rather than replace it. `effect` is `destructive` because a second call is a
- * second bill and a second set of files — never something to retry blindly.
- */
-export declare function writeDocument(opts: WriteDocumentOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
-    readonly name: "brief";
-    readonly type: "text";
-    readonly required: true;
-    readonly maxLength: 8000;
-    readonly description: string;
-}, {
-    readonly name: "format";
-    readonly type: "enum";
-    readonly required: true;
-    readonly options: readonly ["pdf", "pptx", "docx", "md"];
-    readonly description: "pptx for anything presented, pdf for anything sent, docx for anything edited.";
-}, {
-    readonly name: "source";
-    readonly type: "text";
-    readonly required: false;
-    readonly maxLength: 40000;
-    readonly description: string;
-}, {
-    readonly name: "design_notes";
-    readonly type: "text";
-    readonly required: false;
-    readonly maxLength: 2000;
-    readonly description: string;
-}, {
-    readonly name: "session_id";
-    readonly type: "string";
-    readonly required: false;
-    readonly description: string;
-}]>>;
-export { DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign } from "./design.js";
-export { MOA_BASE_URL, MoaApiError, type MoaClientConfig } from "./http.js";
-export type { MoaClient, PollOptions } from "./moa.js";
-export { createMoaClient, INTERACTIVE_TIMEOUT_MS, MoaAbortedError, MoaTimeoutError, pollUntilDone, } from "./moa.js";
-export type { ArtifactFormat, MoaArtifact, MoaInput, MoaResult, MoaStatus, } from "./types.js";

package/dist/agents/moa/index.js

@@ -1 +0,0 @@
-import{tool as f}from"../../tool/index.js";import{DEFAULT_DESIGN as l,mergeDesign as h,renderDesign as g}from"./design.js";import{createMoaClient as p,MoaAbortedError as w,MoaTimeoutError as y,pollUntilDone as M}from"./moa.js";const _=["pdf","pptx","docx","md"],E=6e5,x=2e3,T=4e3;function A(e,r){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 ${r.name??"the house style"}; use \`design_notes\` only for what this one document must do differently.`}function U(e,r,t,d){const i=(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:r,documents:i,delivered:i.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 b(e,r,t){return{taskId:e,status:"running",style:r,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 r=e.formats?.length?e.formats:_,t=h(l,e.design),d=e.maxChars??T,i=e.client??p({apiKey:e.apiKey,baseUrl:e.baseUrl,...e.fetch?{fetch:e.fetch}:{}});return f({name:"write_document",description:A(r,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(!r.includes(s))throw new Error(`write_document was asked for .${s}, which this deployment does not produce (${r.map(n=>`.${n}`).join(", ")}).`);const a=await i.create({task:o,context:u,design:g(t,s,m),artifacts:[s],...c?{sessionId:c}:{}});try{const n=await M(i,a,{timeoutMs:e.timeoutMs??E,settleMs:x,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 U(n,t.name,d,e.includeData===!0)}catch(n){if(n instanceof w&&e.cancelOnAbort!==!1&&await i.cancel?.(a).catch(()=>{}),n instanceof y)return b(a,t.name,n);throw n}}})}import{DEFAULT_DESIGN as $,mergeDesign as q,renderDesign as C}from"./design.js";import{MOA_BASE_URL as O,MoaApiError as R}from"./http.js";import{createMoaClient as N,INTERACTIVE_TIMEOUT_MS as B,MoaAbortedError as j,MoaTimeoutError as z,pollUntilDone as G}from"./moa.js";export{$ as DEFAULT_DESIGN,B as INTERACTIVE_TIMEOUT_MS,O as MOA_BASE_URL,j as MoaAbortedError,R as MoaApiError,z as MoaTimeoutError,N as createMoaClient,q as mergeDesign,G as pollUntilDone,C as renderDesign,L as writeDocument};

package/dist/agents/moa/moa.d.ts

@@ -1,56 +0,0 @@
-import { type AbortSignalLike, type MoaClientConfig } from "./http.js";
-import type { MoaInput, MoaResult } from "./types.js";
-/**
- * Moa's task surface — fire, then await.
- *
- * `create()` hands back an id immediately and `get()` reads it; pass `waitMs`
- * (or use {@link pollUntilDone}) to long-poll, so one call is awaited rather
- * than a loop tight-polling. `cancel()` is optional so a test stub stays small.
- */
-export interface MoaClient {
-    create(input: MoaInput): Promise<string>;
-    get(id: string, opts?: {
-        waitMs?: number;
-        signal?: AbortSignalLike;
-    }): Promise<MoaResult>;
-    cancel?(id: string): Promise<void>;
-}
-/**
- * HTTP {@link MoaClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
- *
- * The request body carries the ask as prose — Moa's artifact pipeline is
- * prompt-driven and `POST /tasks` strips unknown fields, so context, design and
- * deliverables are blocks on the task rather than parameters beside it.
- */
-export declare function createMoaClient(config?: MoaClientConfig): MoaClient;
-/** The sane ceiling for a chat-bound call. A rendered document wants minutes, not this. */
-export declare const INTERACTIVE_TIMEOUT_MS = 30000;
-/** Thrown by {@link pollUntilDone} when the caller's abort signal fires. */
-export declare class MoaAbortedError extends Error {
-    readonly taskId: string;
-    constructor(taskId: string);
-}
-/** Thrown when the wait ran out. The task itself is still running server-side. */
-export declare class MoaTimeoutError extends Error {
-    readonly taskId: string;
-    readonly timeoutMs: number;
-    constructor(taskId: string, timeoutMs: number);
-}
-export interface PollOptions {
-    timeoutMs?: number;
-    pollIntervalMs?: number;
-    /**
-     * Stops the wait and throws {@link MoaAbortedError}, cutting the held
-     * long-poll with it. The task keeps running — cancelling it is the caller's call.
-     */
-    signal?: AbortSignalLike;
-    /**
-     * How long to wait before re-reading a done task whose result has not landed
-     * yet. Moa flips the status slightly before it writes. Default 0.
-     */
-    settleMs?: number;
-    /** Keep settling while a done task carries no artifacts. Set it when files were asked for. */
-    expectArtifacts?: boolean;
-}
-/** Wait for a Moa task to settle, long-polling rather than tight-polling. */
-export declare function pollUntilDone(client: MoaClient, id: string, opts?: PollOptions): Promise<MoaResult>;

package/dist/agents/moa/moa.js

@@ -1,13 +0,0 @@
-import{createRequest as w,MoaApiError as M}from"./http.js";const h={queued:"pending",running:"running",succeeded:"done",failed:"failed",canceled:"failed"},T=["md","pdf","docx","pptx"],g=n=>{const t=n?.split(".").pop()?.toLowerCase();return t&&T.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 p(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 M("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)}`:"",r=await t(`/tasks/${encodeURIComponent(e)}${c}`,{signal:s?.signal}),a=r.status?h[r.status]:void 0;return{id:r.id??e,status:a??"running",output:r.result,error:r.error,costUsd:r.costUsd,numTurns:r.numTurns,sessionId:r.sessionId,artifacts:E(r.artifacts)}},async cancel(e){await t(`/tasks/${encodeURIComponent(e)}`,{method:"DELETE"})}}}const k=3e4,b=2e3,A=3,y=25e3;class f extends Error{taskId;constructor(t){super(`Moa task ${t} was cancelled by the caller.`),this.name="MoaAbortedError",this.taskId=t}}class S extends Error{taskId;timeoutMs;constructor(t,e){super(`Moa task ${t} did not complete within ${e/1e3}s. The task may still be running in the background.`),this.name="MoaTimeoutError",this.taskId=t,this.timeoutMs=e}}const m=(n,t)=>new Promise(e=>{const s=()=>e();t?.addEventListener("abort",s,{once:!0}),setTimeout(()=>{t?.removeEventListener("abort",s),e()},n)});async function L(n,t,e={}){const s=e.timeoutMs??k,c=e.pollIntervalMs??b,r=e.settleMs??0,a=e.signal,l=Date.now()+s;for(;;){if(a?.aborted)throw new f(t);const u=l-Date.now();if(u<=0)throw new S(t,s);let o;try{o=await n.get(t,{waitMs:Math.min(u,y),signal:a})}catch(d){throw a?.aborted?new f(t):d}if(o.status==="failed")return o;if(o.status==="done"){const d=i=>!i.output?.trim()||e.expectArtifacts===!0&&!i.artifacts?.length;for(let i=0;r>0&&i<A&&d(o);i++)await m(r),o=await n.get(t);return o}await m(Math.min(c,Math.max(0,l-Date.now())),a)}}export{k as INTERACTIVE_TIMEOUT_MS,f as MoaAbortedError,S as MoaTimeoutError,p as createMoaClient,L as pollUntilDone};

package/dist/agents/moa/types.d.ts

@@ -1,33 +0,0 @@
-/** A document format Moa can leave behind in `artifacts/`. */
-export type ArtifactFormat = "md" | "pdf" | "docx" | "pptx";
-/** Where a Moa task has got to. `pending` is queued, `failed` is settled. */
-export type MoaStatus = "pending" | "running" | "done" | "failed";
-/** One finished file, either downloadable or carried inline as base64. */
-export interface MoaArtifact {
-    name: string;
-    format: ArtifactFormat;
-    url?: string;
-    data?: string;
-    mime?: string;
-    sizeBytes?: number;
-}
-/** What to hand Moa: the ask, the material it rests on, and the house style. */
-export interface MoaInput {
-    task: string;
-    context?: string;
-    design?: string;
-    artifacts?: readonly ArtifactFormat[];
-    sessionId?: string;
-    newSessionId?: string;
-}
-/** A Moa task as it stands right now. */
-export interface MoaResult {
-    id: string;
-    status: MoaStatus;
-    output?: string;
-    error?: string;
-    costUsd?: number;
-    numTurns?: number;
-    sessionId?: string;
-    artifacts?: MoaArtifact[];
-}

package/dist/builtin/openalex/render.js

@@ -1,4 +0,0 @@
-const h=3;function c(n){const t=n.authors.slice(0,3).map(e=>e.split(" ").at(-1)??e),o=n.authors.length-t.length;return t.length===0?"unknown authors":o>0?`${t.join(", ")} +${o}`:t.join(", ")}function $(n){const t=n.year===null?"":` (${n.year})`,o=n.venue?` \xB7 ${n.venue}`:"";return`${n.title}${t} \u2014 ${c(n)}${o} \xB7 ${n.citations} citations`}function d(n){const o=[n.doi?`doi:${n.doi}`:null,n.pdf?`pdf: ${n.pdf}`:null].filter(e=>e!==null);return o.length>0?o.join(" \xB7 "):null}function f(n,t){const o=n.abstract.trim();return o?o.length>t?`${o.slice(0,t).trimEnd()}\u2026`:o:null}function m(n,t,o){const e=`${t.length} paper${t.length===1?"":"s"} on "${n}", most relevant first`,u=t.map((l,s)=>[`${s+1}. ${$(l)}`,d(l),f(l,o)].filter(i=>i!==null).map((i,r)=>r===0?i:`   ${i}`).join(`
-`));return[e,...u].join(`
-
-`)}export{m as rendered};