@spendgraph/tools 0.6.0 → 0.7.0

package/dist/bus/group.js

@@ -1 +1 @@
-import{toAnthropic as O,toMarkdown as I,toOpenAI as $}from"../wire/index.js";import{scorerFor as k}from"./score.js";import{toStep as A}from"./step.js";import{ceilingFor as M,termsIn as T}from"./terms.js";import{newTrace as x}from"./trace.js";const B=6,v=3;function D(t){return{name:t.name,description:t.description,args:[]}}function F(t){const s=new Map;for(const e of t)for(const o of e.bus.all()){const c=s.get(o.name);if(c)throw new Error(`Two buses offer a tool called "${o.name}": "${c.name}" and "${e.name}". A name has to say which one runs.`);s.set(o.name,e)}return s}function S(t){return t.flatMap(s=>{const e=s.bus.all().filter(o=>o.pinned).map(o=>o.name);return e.length>0?s.bus.declarations(e):[]})}function C(t){const s=[],e=new Set;let o=t;return{chosen:s,holds:c=>e.has(c),full:()=>s.length>=o,room:()=>t-s.length,narrowTo:c=>{o=Math.min(o,c)},take(c){e.has(c.name)||s.length>=o||(e.add(c.name),s.push(c))}}}function L(t,s,e){const o=t.flat(),c=k(o),f=o.map(l=>({declaration:l,n:c(l,s)})).sort((l,u)=>u.n-l.n);if(f.length===0||f[0].n===0)return!1;f.length>1&&f[0].n>=f[1].n*2&&e.narrowTo(e.chosen.length+v);for(const{declaration:l}of f){if(e.full())break;e.take(l)}return!0}function N(t,s){for(let e=0;!s.full();e++){let o=!1;for(const c of t){const f=c[e];if(f!==void 0&&(o=!0,s.take(f),s.full()))break}if(!o)break}}function z(t,s={}){const e=new Set;for(const n of t){if(e.has(n.name))throw new Error(`Two buses are called "${n.name}".`);e.add(n.name)}const o=F(t),c=S(t),f=new Map(t.map(n=>[n,D(n)])),m=k([...f.values()]),l=M(s.limit,B),u=n=>o.get(n),b=()=>t.flatMap(n=>n.bus.all()),p=()=>t.flatMap(n=>n.bus.declarations()),y=n=>t.map(a=>({member:a,n:m(f.get(a),n)})).sort((a,r)=>r.n-a.n),g={all:b,missing:n=>n.filter(a=>!o.has(a)),get:n=>u(n)?.bus.get(n),effectOf:n=>u(n)?.bus.effectOf(n),destructive:()=>t.flatMap(n=>n.bus.destructive()),unannotated:()=>t.flatMap(n=>n.bus.unannotated()),declarations:n=>n?t.flatMap(a=>{const r=n.filter(i=>o.get(i)===a);return r.length>0?a.bus.declarations(r):[]}):p(),anthropic:n=>O(n??p()),openai:n=>$(n??p()),markdown:(n,a)=>I(n??p(),a),select:(n="",a)=>{const r=C(M(a,l));for(const h of c)r.take(h);const i=r.room();if(i<=0)return r.chosen;const d=y(T(n)),w=d.map(({member:h})=>h.bus.select(n,i).filter(E=>!r.holds(E.name)));if(d.length>1&&d[0].n>0&&d[0].n>=d[1].n*2&&w[0].length>0){r.narrowTo(r.chosen.length+v);for(const h of w[0])r.take(h);return r.chosen}return L(w,T(n),r)||N(w,r),r.chosen},invoke:async(n,a)=>{const r=u(n);return r?r.bus.invoke(n,a):{name:n,args:a,status:"failed",output:"",error:`No tool called "${n}". Offered: ${[...o.keys()].join(", ")}`,latencyMs:0}},usage:()=>Object.assign({},...t.map(n=>n.bus.usage())),step:(n,a)=>A(n,a),trace:(n="",a)=>x(g.select(n,a),(r,i)=>g.invoke(r,i))};return g}export{z as busgroup};
+import{toAnthropic as T,toMarkdown as b,toOpenAI as E}from"../wire/index.js";import{naming as N}from"./namespace.js";import{scorerFor as I}from"./score.js";import{toStep as S}from"./step.js";import{ceilingFor as $,termsIn as A}from"./terms.js";import{newTrace as j}from"./trace.js";const C=6,x=3;function L(r){return{name:r.name,description:r.description,args:[]}}function G(r,f){const a=new Map;for(const o of r)for(const c of o.bus.all()){const l=f.offered(o,c.name),w=a.get(l);if(w)throw new Error(`Two buses offer a tool called "${l}": "${w.name}" and "${o.name}". A name has to say which one runs \u2014 set \`namespace\` to name them after their bus.`);a.set(l,o)}return a}function U(r,f){return r.flatMap(a=>{const o=a.bus.all().filter(c=>c.pinned).map(c=>c.name);return o.length>0?v(a,f,a.bus.declarations(o)):[]})}const v=(r,f,a)=>a.map(o=>({...o,name:f.offered(r,o.name)}));function _(r){const f=[],a=new Set;let o=r;return{chosen:f,holds:c=>a.has(c),full:()=>f.length>=o,room:()=>r-f.length,narrowTo:c=>{o=Math.min(o,c)},take(c){a.has(c.name)||f.length>=o||(a.add(c.name),f.push(c))}}}function K(r,f,a){const o=r.flat(),c=I(o),l=o.map(d=>({declaration:d,n:c(d,f)})).sort((d,O)=>O.n-d.n);if(l.length===0||l[0].n===0)return!1;l.length>1&&l[0].n>=l[1].n*2&&a.narrowTo(a.chosen.length+x);for(const{declaration:d}of l){if(a.full())break;a.take(d)}return!0}function P(r,f){for(let a=0;!f.full();a++){let o=!1;for(const c of r){const l=c[a];if(l!==void 0&&(o=!0,f.take(l),f.full()))break}if(!o)break}}function W(r,f={}){const a=new Set;for(const n of r){if(a.has(n.name))throw new Error(`Two buses are called "${n.name}".`);a.add(n.name)}const o=N(r,f.namespace),c=G(r,o),l=U(r,o),w=new Map(r.map(n=>[n,L(n)])),d=I([...w.values()]),O=$(f.limit,C),m=n=>c.get(n),g=(n,t)=>o.owned(n,t),y=()=>r.flatMap(n=>n.bus.all().map(t=>({...t,name:o.offered(n,t.name)}))),k=()=>r.flatMap(n=>v(n,o,n.bus.declarations())),B=(n,t)=>Object.fromEntries(Object.entries(t).map(([e,u])=>[o.offered(n,e),u])),D=n=>r.map(t=>({member:t,n:d(w.get(t),n)})).sort((t,e)=>e.n-t.n),h={all:y,missing:n=>n.filter(t=>!c.has(t)),get:n=>{const t=m(n),e=t?.bus.get(g(t,n));return e&&t?{...e,name:n}:e},effectOf:n=>{const t=m(n);return t?.bus.effectOf(g(t,n))},trustOf:n=>{const t=m(n);return t?.bus.trustOf(g(t,n))},destructive:()=>r.flatMap(n=>n.bus.destructive().map(t=>o.offered(n,t))),unannotated:()=>r.flatMap(n=>n.bus.unannotated().map(t=>o.offered(n,t))),declarations:n=>n?r.flatMap(t=>{const e=n.filter(s=>c.get(s)===t);if(e.length===0)return[];const u=e.map(s=>g(t,s));return v(t,o,t.bus.declarations(u))}):k(),anthropic:n=>T(n??k()),openai:n=>E(n??k()),markdown:(n,t)=>b(n??k(),t),select:(n="",t)=>{const e=_($(t,O));for(const p of l)e.take(p);const u=e.room();if(u<=0)return e.chosen;const s=D(A(n)),i=s.map(({member:p})=>v(p,o,p.bus.select(n,u)).filter(F=>!e.holds(F.name)));if(s.length>1&&s[0].n>0&&s[0].n>=s[1].n*2&&i[0].length>0){e.narrowTo(e.chosen.length+x);for(const p of i[0])e.take(p);return e.chosen}return K(i,A(n),e)||P(i,e),e.chosen},invoke:async(n,t)=>{const e=m(n);return e?{...await e.bus.invoke(g(e,n),t),name:n}:{name:n,args:t,status:"failed",output:"",error:`No tool called "${n}". Offered: ${[...c.keys()].join(", ")}`,latencyMs:0}},usage:()=>Object.assign({},...r.map(n=>B(n,n.bus.usage()))),step:(n,t)=>S(n,t),trace:(n="",t)=>j(h.select(n,t),(e,u)=>h.invoke(e,u)),only:n=>{const t=n.filter(s=>c.has(s)),e=()=>h.declarations(t),u={...h,all:()=>y().filter(s=>t.includes(s.name)),missing:s=>s.filter(i=>!t.includes(i)),declarations:s=>s?e().filter(i=>s.includes(i.name)):e(),anthropic:s=>T(s??e()),openai:s=>E(s??e()),markdown:(s,i)=>b(s??e(),i),select:(s="",i)=>h.select(s,i).filter(M=>t.includes(M.name)),trace:(s="",i)=>j(u.select(s,i),(M,p)=>h.invoke(M,p))};return u}};return h}export{W as busgroup};

package/dist/bus/index.d.ts

@@ -1,4 +1,7 @@
 export { type ToolBus, toolbus } from "./bus.js";
-export { type BusMember, busgroup } from "./group.js";
+export { type BusGroupOptions, type BusMember, busgroup } from "./group.js";
+export type { Namespacing } from "./namespace.js";
+export type { Offering } from "./only.js";
 export type { ToolBusOptions } from "./options.js";
+export { priced, spentOn } from "./spent.js";
 export { newTrace, type ToolTrace } from "./trace.js";

package/dist/bus/index.js

@@ -1 +1 @@
-import{toolbus as e}from"./bus.js";import{busgroup as t}from"./group.js";import{newTrace as m}from"./trace.js";export{t as busgroup,m as newTrace,e as toolbus};
+import{toolbus as e}from"./bus.js";import{busgroup as t}from"./group.js";import{priced as m,spentOn as x}from"./spent.js";import{newTrace as s}from"./trace.js";export{t as busgroup,s as newTrace,m as priced,x as spentOn,e as toolbus};

package/dist/bus/invoke.d.ts

@@ -6,4 +6,4 @@ import type { Tool, ToolResult } from "../types/index.js";
  * step worth recording, not an exception that ends the run — the same argument
  * `status` and `error` exist on a rollout for.
  */
-export declare function invokeTool(byName: Map<string, Tool<never>>, calls: Map<string, number>, now: () => number, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+export declare function invokeTool(byName: Map<string, Tool<never>>, calls: Map<string, number>, now: () => number, name: string, args: Record<string, unknown>, maxOutputChars?: number): Promise<ToolResult>;

package/dist/bus/invoke.js

@@ -1 +1,3 @@
-import{FieldValidationError as d,validateFields as f}from"@spendgraph/sdk";import{readyArgs as p}from"./args.js";import{reasonFor as y,render as g}from"./output.js";async function F(n,i,r,t,s){const a=r(),e=n.get(t),o={name:t,args:s,latencyMs:0};if(!e)return{...o,status:"failed",output:"",error:`No tool called "${t}". Offered: ${[...n.keys()].join(", ")}`};const l=f(s,e.args);if(l.length>0)return{...o,status:"failed",output:"",error:new d(l).message,latencyMs:r()-a};i.set(t,(i.get(t)??0)+1);const c=p(e.args,s);try{const u=await e.run(c);return{...o,status:"completed",output:g(u),latencyMs:r()-a}}catch(u){return{...o,status:"failed",output:"",error:y(u),latencyMs:r()-a}}}export{F as invokeTool};
+import{FieldValidationError as d,validateFields as y}from"@spendgraph/sdk";import{readyArgs as g}from"./args.js";import{reasonFor as h,render as p}from"./output.js";function M(r,e){if(e===void 0||r.length<=e)return{output:r};const t=Math.max(0,e);return{output:`${r.slice(0,t)}
+
+[cut: showing the first ${t} of ${r.length} characters]`,truncated:{kept:t,of:r.length}}}function $(r){const e=r?.results;if(!Array.isArray(e))return{};const t=e.filter(s=>!!s&&typeof s.url=="string"&&s.url!=="");return t.length?{sources:t}:{}}function k(r,e){if(!r.costOf)return{};try{const t=r.costOf(e);return typeof t=="number"&&Number.isFinite(t)&&t>=0?{costMicros:t}:{}}catch{return{}}}async function A(r,e,t,s,u,f){const i=t(),n=r.get(s),c={name:s,args:u,latencyMs:0,...n?.trust?{trust:n.trust}:{}};if(!n)return{...c,status:"failed",output:"",error:`No tool called "${s}". Offered: ${[...r.keys()].join(", ")}`};const a=y(u,n.args);if(a.length>0)return{...c,status:"failed",output:"",error:new d(a).message,latencyMs:t()-i};e.set(s,(e.get(s)??0)+1);const l=g(n.args,u);try{const o=await n.run(l);return{...c,status:"completed",...M(p(o),f),latencyMs:t()-i,...k(n,o),...$(o)}}catch(o){return{...c,status:"failed",output:"",error:h(o),latencyMs:t()-i}}}export{A as invokeTool};

package/dist/bus/namespace.d.ts

@@ -0,0 +1,21 @@
+import type { BusMember } from "./group.js";
+/** How a grouped tool is named to the model. */
+export type Namespacing = boolean | ((member: string, tool: string) => string);
+export interface Naming {
+    /** What the model is offered, given a tool's own name on its bus. */
+    offered(member: BusMember, tool: string): string;
+    /** Back to the name the owning bus knows, given a name the model used. */
+    owned(member: BusMember, offered: string): string;
+}
+/**
+ * Names every tool after the bus that runs it, or leaves them all alone.
+ *
+ * Off by default, because a name that says nothing about who runs it is a name
+ * worth fixing at the source. It is not always yours to fix: a group standing
+ * in front of several servers you do not own will meet two of them offering
+ * `search`, and refusing to start is not better than disambiguating.
+ *
+ * Built eagerly from what each bus holds, so the reverse lookup is complete
+ * before the first call rather than filled in as names happen to be asked for.
+ */
+export declare function naming(members: BusMember[], how: Namespacing | undefined): Naming;

package/dist/bus/namespace.js

@@ -0,0 +1 @@
+const d="__",p=(o,t)=>`${o}__${t}`;function u(o,t){if(!t)return{offered:(n,e)=>e,owned:(n,e)=>e};const r=typeof t=="function"?t:p,m=new Map,s=new Map;for(const n of o){const e=new Map,f=new Map;for(const a of n.bus.all()){const c=r(n.name,a.name);e.set(a.name,c),f.set(c,a.name)}m.set(n.name,e),s.set(n.name,f)}return{offered:(n,e)=>m.get(n.name)?.get(e)??e,owned:(n,e)=>s.get(n.name)?.get(e)??e}}export{u as naming};

package/dist/bus/once.d.ts

@@ -0,0 +1,32 @@
+import type { Tool, ToolResult } from "../types/index.js";
+/**
+ * The same call again: the tool, and the arguments in a stable order.
+ *
+ * Sorted, because a model writing `{invoice, amount}` on one turn and
+ * `{amount, invoice}` on the next means the same call, and a key that said
+ * otherwise would let the second one through — which is the whole failure.
+ */
+export declare const callKey: (name: string, args: Record<string, unknown>) => string;
+/**
+ * Remembers what each destructive call already did, so a repeat does not do it twice.
+ *
+ * The agent runtime retries — after a timeout, a crash, a redelivery — and that
+ * is correct; the tool layer is where a repeat has to stop being a second
+ * refund. `effect` has always said which calls need this and nothing has ever
+ * read it: `destructive` is precisely the label for a call that is not safe to
+ * repeat, and `idempotent` is the label for one that is.
+ *
+ * Only completed calls are remembered. A failed one is exactly what a retry is
+ * for, and refusing to try again because the first attempt fell over would turn
+ * every transient error into a permanent one.
+ *
+ * A tool that declared no effect is not covered. Unset means nobody has said,
+ * which is not the same as safe — the package cannot invent the label, and
+ * quietly deduplicating an unlabelled call would be a guess about somebody
+ * else's API.
+ */
+export declare function onceEach(): {
+    /** The earlier result for this exact destructive call, when there is one. */
+    earlier(tool: Tool<never> | undefined, name: string, args: Record<string, unknown>): ToolResult | undefined;
+    keep(tool: Tool<never> | undefined, result: ToolResult): void;
+};

package/dist/bus/once.js

@@ -0,0 +1 @@
+const r=t=>{if(t===null||typeof t!="object")return JSON.stringify(t)??"";if(Array.isArray(t))return`[${t.map(r).join(",")}]`;const n=t;return`{${Object.keys(n).sort().map(e=>`${JSON.stringify(e)}:${r(n[e])}`).join(",")}}`},c=(t,n)=>`${t}::${r(n)}`;function o(){const t=new Map;return{earlier(n,e,i){if(n?.effect==="destructive")return t.get(c(e,i))},keep(n,e){n?.effect!=="destructive"||e.status!=="completed"||t.set(c(e.name,e.args),e)}}}export{c as callKey,o as onceEach};

package/dist/bus/only.d.ts

@@ -0,0 +1,29 @@
+import type { Effect, Tool, ToolDeclaration, ToolResult } from "../types/index.js";
+import type { AnthropicTool, OpenAITool } from "../wire/index.js";
+import type { ToolTrace } from "./trace.js";
+/**
+ * A bus narrowed to some of its tools.
+ *
+ * The declaring half is the half that changes: a model is shown these, and
+ * everything reaches the same `invoke` underneath. Written out rather than
+ * derived from `toolbus`, because a type that referred back to its own return
+ * would be circular — and because what a view promises is worth saying once.
+ */
+export interface Offering {
+    /** The tools in this view, in declaration order. */
+    all(): Tool<never>[];
+    get(name: string): Tool<never> | undefined;
+    /** Names this view does not offer, whether or not the bus behind it has them. */
+    missing(names: string[]): string[];
+    effectOf(name: string): Effect | undefined;
+    declarations(names?: string[]): ToolDeclaration[];
+    anthropic(decls?: ToolDeclaration[]): AnthropicTool[];
+    openai(decls?: ToolDeclaration[]): OpenAITool[];
+    markdown(decls?: ToolDeclaration[], heading?: string): string;
+    select(query?: string, limit?: number): ToolDeclaration[];
+    /** Runs one, through the bus this view came from. */
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** How often each has been called on the bus behind this view. */
+    usage(): Record<string, number>;
+    trace(query?: string, limit?: number): ToolTrace;
+}

package/dist/bus/options.d.ts

@@ -19,4 +19,35 @@ export interface ToolBusOptions {
      * often, which is why it is worth saying at construction.
      */
     warnOnOverlap?: boolean;
+    /**
+     * Longest output a tool may return, in characters. No cap by default.
+     *
+     * One tool handing back a whole document fills a window on its own, and the
+     * failure is silent: no error, a clean call, a clean reply, and an answer
+     * that is wrong in the same tone as a right one. Nothing downstream can tell
+     * a tool that found three matches from one that found three hundred and was
+     * cut after three.
+     *
+     * Cut output says so, twice: a line the model reads at the end of the text,
+     * and `truncated` on the result for code that needs to count it. A model told
+     * it is looking at part of something asks again; one that is not, answers.
+     *
+     * No default, because a cap is a statement about your context window and your
+     * tools, and a number chosen here would be wrong for both. The builtins that
+     * fetch carry their own `maxChars` for the same reason.
+     */
+    maxOutputChars?: number;
+    /**
+     * Run each destructive call once, however many times it is asked for.
+     *
+     * A repeat of a call that already completed gets the first result back
+     * without the tool running again, marked `repeated` so an operator can count
+     * it. `readonly` and `idempotent` calls run every time, which is what those
+     * labels mean; a tool that declared no effect is not covered.
+     *
+     * Off by default. Deduplication is scoped to one bus, so what counts as "the
+     * same call again" is a decision about how long a bus lives — one per run, one
+     * per session, one per process — and the package cannot make it for you.
+     */
+    onceEach?: boolean;
 }

package/dist/bus/select.d.ts

@@ -1,19 +1,3 @@
 import type { Tool, ToolDeclaration } from "../types/index.js";
 import type { Scorer } from "./score.js";
-/**
- * The working set for one request: pinned, then what the query matches, then
- * what actually gets used.
- *
- * Relevance before usage, which is the opposite of what this did first. At a
- * shortlist of twelve the order was harmless; at six, three previously-used
- * tools take half the slots and push out the tool the query needs.
- *
- * Usage still earns its place as the tiebreaker among equal matches, and as the
- * fallback when nothing matches — the case where an agent would otherwise be
- * handed nothing.
- *
- * How many come back depends on how clearly the query matched. A single strong
- * match needs no company; a flat spread means the ranking does not know, and a
- * wider net is worth the distraction.
- */
 export declare function selectTools(tools: Tool<never>[], calls: Map<string, number>, declare: (t: Tool<never>) => ToolDeclaration, scoreOf: Scorer, query: string, ceiling: number): ToolDeclaration[];

package/dist/bus/select.js

@@ -1 +1 @@
-import{termsIn as u}from"./terms.js";function v(m,e,h,a,p,f){const d=u(p),n=[],r=t=>{!n.includes(t)&&n.length<f&&n.push(t)};for(const t of m)t.pinned&&r(t);const i=m.filter(t=>!t.pinned),o=i.map(t=>({t,n:a(t,d)})).filter(t=>t.n>0).sort((t,s)=>s.n-t.n||(e.get(s.t.name)??0)-(e.get(t.t.name)??0)),c=f-n.length,k=o.length>1&&o[0].n>=o[1].n*2,g=n.length+(k?Math.min(3,c):c);for(const{t}of o){if(n.length>=g)break;r(t)}const b=[...i].sort((t,s)=>(e.get(s.name)??0)-(e.get(t.name)??0));for(const t of b){if(n.length>=g||(e.get(t.name)??0)===0)break;r(t)}if(o.length===0)for(const t of i){if(n.length>=f)break;r(t)}return n.map(h)}export{v as selectTools};
+import{termsIn as l}from"./terms.js";function w(t,o,g){if(!t.some(f=>f.needs?.length))return t;const r=[];for(const f of t){if(r.includes(f))continue;const s=(f.needs??[]).map(i=>o.get(i)).filter(i=>i!==void 0&&!r.includes(i));r.length+1+s.length>g||r.push(f,...s)}return r}function M(t,o,g,r,f,s){const i=new Map(t.map(n=>[n.name,n])),p=l(f),e=[],m=n=>{!e.includes(n)&&e.length<s&&e.push(n)};for(const n of t)n.pinned&&m(n);const d=t.filter(n=>!n.pinned),c=d.map(n=>({t:n,n:r(n,p)})).filter(n=>n.n>0).sort((n,a)=>a.n-n.n||(o.get(a.t.name)??0)-(o.get(n.t.name)??0)),u=s-e.length,k=c.length>1&&c[0].n>=c[1].n*2,h=e.length+(k?Math.min(3,u):u);for(const{t:n}of c){if(e.length>=h)break;m(n)}const b=[...d].sort((n,a)=>(o.get(a.name)??0)-(o.get(n.name)??0));for(const n of b){if(e.length>=h||(o.get(n.name)??0)===0)break;m(n)}if(c.length===0)for(const n of d){if(e.length>=s)break;m(n)}return w(e,i,s).map(g)}export{M as selectTools};

package/dist/bus/spent.d.ts

@@ -0,0 +1,16 @@
+import type { ToolResult } from "../types/index.js";
+/**
+ * What the tools themselves cost, in micro-USD.
+ *
+ * A run's token counts are the outer model's. A tool that spends on its own —
+ * a deep recall, a judge, a sub-agent — is not in them, so a loop that called
+ * three of those reports a bill that is missing most of itself. Only results
+ * from tools that declared a `costOf` count; the rest are not free, they are
+ * unmeasured, and those are different claims.
+ */
+export declare function spentOn(results: readonly ToolResult[]): number;
+/** The calls that reported a price, so an unmeasured one is visible as an absence. */
+export declare function priced(results: readonly ToolResult[]): {
+    name: string;
+    costMicros: number;
+}[];

package/dist/bus/spent.js

@@ -0,0 +1 @@
+function c(o){let t=0;for(const r of o)t+=r.costMicros??0;return t}function e(o){return o.filter(t=>t.costMicros!==void 0).map(t=>({name:t.name,costMicros:t.costMicros}))}export{e as priced,c as spentOn};

package/dist/bus/trace.d.ts

@@ -18,7 +18,12 @@ export interface ToolTrace {
      * never said — and for one that was never offered.
      */
     effectOf(name: string): Effect | undefined;
-    /** Runs a tool and records the step. Never throws, exactly as `invoke`. */
+    /**
+     * Runs a tool this turn offered and records the step. Never throws.
+     *
+     * A name that was not offered comes back as a failed result naming what was,
+     * without reaching the bus — see `newTrace`.
+     */
     invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
     /** The steps so far, in call order. */
     steps(): RolloutStep[];
@@ -38,5 +43,13 @@ export interface ToolTrace {
  *
  * Selection happens once, here, and the same list is what gets reported. A trace
  * cannot disagree with itself about what the model saw.
+ *
+ * It also cannot run what it did not offer. A shortlist narrows the declarations
+ * and used to hand `invoke` the whole bus, so a name the model produced out of
+ * nowhere still ran if anything on the bus happened to be called that — and the
+ * rollout came back with a step that had no matching entry in `offeredTools`,
+ * which reads as impossible. The refusal is a failed result rather than a throw,
+ * carrying the names that were offered, because that is an observation the model
+ * can correct from on its next turn; an exception is one the run dies of.
  */
 export declare function newTrace(offered: ToolDeclaration[], invoke: (name: string, args: Record<string, unknown>) => Promise<ToolResult>): ToolTrace;

package/dist/bus/trace.js

@@ -1 +1 @@
-import{toAnthropic as s,toMarkdown as a,toOpenAI as c}from"../wire/index.js";import{toStep as i}from"./step.js";function h(n,r){const o=[];return{offered:n,anthropic:()=>s(n),openai:()=>c(n),markdown:t=>a(n,t),effectOf:t=>n.find(e=>e.name===t)?.effect,invoke:async(t,e)=>{const p=await r(t,e);return o.push(i(p,o.length)),p},steps:()=>[...o],record:()=>({offeredTools:n.map(t=>t.name),steps:[...o]})}}export{h as newTrace};
+import{toAnthropic as p,toMarkdown as c,toOpenAI as i}from"../wire/index.js";import{toStep as u}from"./step.js";function m(t,r,o){return{name:t,args:r,status:"failed",output:"",error:`No tool called "${t}" was offered this turn. Offered: ${o.map(n=>n.name).join(", ")}`,latencyMs:0}}function h(t,r){const o=[];return{offered:t,anthropic:()=>p(t),openai:()=>i(t),markdown:n=>c(t,n),effectOf:n=>t.find(e=>e.name===n)?.effect,invoke:async(n,e)=>{const s=t.some(a=>a.name===n)?await r(n,e):m(n,e,t);return o.push(u(s,o.length)),s},steps:()=>[...o],record:()=>({offeredTools:t.map(n=>n.name),steps:[...o]})}}export{h as newTrace};

package/dist/index.d.ts

@@ -7,10 +7,12 @@
  * converters themselves, for a caller adapting a declaration by hand.
  */
 export type { RolloutStep } from "@spendgraph/sdk";
-export { type ArtifactFormat, answerOf, type ClockOptions, type CodeExecOptions, CommissionAbortedError, type CommissionClient, CommissionTimeoutError, calculate, codeExec, currentTime, DEFAULT_DESIGN, type DeepRecallOptions, type DesignGuide, dateMath, deepRecall, type EscalateOptions, type EscalationRequest, escalate, type Finished, finish, type HttpOptions, httpRequest, isFinished, type JsonQueryOptions, jsonQuery, mergeDesign, type RecalledFact, type Recaller, type RecallResult, renderDesign, type Sandbox, type SandboxRequest, type SandboxResult, type SearchDepth, think, type WebSearchOptions, type WriteDocumentOptions, webSearch, writeDocument, } from "./builtin/index.js";
-export type { BusMember, ToolBus, ToolBusOptions, ToolTrace } from "./bus/index.js";
-export { busgroup, toolbus } from "./bus/index.js";
+export { type ArtifactFormat, DEFAULT_DESIGN, type DesignGuide, MoaAbortedError, type MoaClient, MoaTimeoutError, mergeDesign, renderDesign, type WriteDocumentOptions, writeDocument, } from "./agents/index.js";
+export { answerOf, type ClockOptions, type CodeExecOptions, calculate, codeExec, currentTime, type Declined, dateMath, dates, decline, declinedFor, type EscalateOptions, type EscalationRequest, type ExtractOptions, escalate, escalationOf, extract, type Finished, finish, type HttpOptions, httpRequest, isDeclined, isEscalated, isFinished, type JsonQueryOptions, jsonFrom, jsonQuery, type NotesOptions, type NotesStore, notes, notesStore, type OpenAlexApi, type OpenAlexOptions, openalex, type Publisher, type PublishOptions, publish, retryAfterMs, type Sandbox, type SandboxRequest, type SandboxResult, type SearchDepth, think, type Unanswerable, type WebSearchOptions, type WikidataApi, type WikidataOptions, webSearch, wikidata, } from "./builtin/index.js";
+export type { BusGroupOptions, BusMember, Namespacing, Offering, ToolBus, ToolBusOptions, ToolTrace, } from "./bus/index.js";
+export { busgroup, priced, spentOn, toolbus } from "./bus/index.js";
+export { contextId, type DeepRecallOptions, deepRecall, type ExploreOptions, exploreMemory, type MemoriesOptions, type MemoryClient, type MemoryContext, type MemoryGraph, type MemoryKind, type MemorySet, type MemorySource, type Moment, type MomentSource, memories, type Observer, type ObserverOptions, observer, type RecalledFact, type Recaller, type RecallFormat, type RecallOptions, type RecallResult, type RememberOptions, recall, remember, } from "./memories/index.js";
 export type { BoundSpec, ToolSpec } from "./tool/index.js";
 export { bindTool, ToolDriftError, ToolNotStoredError, tool } from "./tool/index.js";
-export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration, ToolResult, } from "./types/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Effect, Tool, ToolDeclaration, ToolResult, Trust, } from "./types/index.js";
 export type { AnthropicTool, JsonSchema, JsonSchemaProperty, OpenAITool, } from "./wire/index.js";

package/dist/index.js

@@ -1 +1 @@
-import{answerOf as r,CommissionAbortedError as t,CommissionTimeoutError as i,calculate as s,codeExec as n,currentTime as m,DEFAULT_DESIGN as l,dateMath as a,deepRecall as c,escalate as u,finish as d,httpRequest as E,isFinished as f,jsonQuery as h,mergeDesign as p,renderDesign as D,think as T,webSearch as b,writeDocument as g}from"./builtin/index.js";import{busgroup as w,toolbus as S}from"./bus/index.js";import{bindTool as C,ToolDriftError as F,ToolNotStoredError as N,tool as R}from"./tool/index.js";export{t as CommissionAbortedError,i as CommissionTimeoutError,l as DEFAULT_DESIGN,F as ToolDriftError,N as ToolNotStoredError,r as answerOf,C as bindTool,w as busgroup,s as calculate,n as codeExec,m as currentTime,a as dateMath,c as deepRecall,u as escalate,d as finish,E as httpRequest,f as isFinished,h as jsonQuery,p as mergeDesign,D as renderDesign,T as think,R as tool,S as toolbus,b as webSearch,g as writeDocument};
+import{DEFAULT_DESIGN as o,MoaAbortedError as t,MoaTimeoutError as i,mergeDesign as s,renderDesign as n,writeDocument as a}from"./agents/index.js";import{answerOf as c,calculate as d,codeExec as m,currentTime as p,dateMath as f,dates as u,decline as x,declinedFor as b,escalate as E,escalationOf as h,extract as D,finish as T,httpRequest as M,isDeclined as g,isEscalated as w,isFinished as F,jsonFrom as S,jsonQuery as y,notes as A,notesStore as O,openalex as j,publish as k,retryAfterMs as I,think as N,webSearch as R,wikidata as q}from"./builtin/index.js";import{busgroup as G,priced as L,spentOn as Q,toolbus as U}from"./bus/index.js";import{contextId as z,deepRecall as B,exploreMemory as C,memories as H,observer as J,recall as K,remember as P}from"./memories/index.js";import{bindTool as W,ToolDriftError as X,ToolNotStoredError as Y,tool as Z}from"./tool/index.js";export{o as DEFAULT_DESIGN,t as MoaAbortedError,i as MoaTimeoutError,X as ToolDriftError,Y as ToolNotStoredError,c as answerOf,W as bindTool,G as busgroup,d as calculate,m as codeExec,z as contextId,p as currentTime,f as dateMath,u as dates,x as decline,b as declinedFor,B as deepRecall,E as escalate,h as escalationOf,C as exploreMemory,D as extract,T as finish,M as httpRequest,g as isDeclined,w as isEscalated,F as isFinished,S as jsonFrom,y as jsonQuery,H as memories,s as mergeDesign,A as notes,O as notesStore,J as observer,j as openalex,L as priced,k as publish,K as recall,P as remember,n as renderDesign,I as retryAfterMs,Q as spentOn,N as think,Z as tool,U as toolbus,R as webSearch,q as wikidata,a as writeDocument};

package/dist/internals.d.ts

@@ -4,7 +4,14 @@
  * Not in the main entry: a bus already wires all of it, and a caller reaching
  * here is building their own. Kept exported so that stays possible.
  */
-export { evaluate } from "./builtin/calculate/index.js";
+/**
+ * The arithmetic behind `calculate`, and the way it renders a result.
+ *
+ * Both, because either alone is half a comparison. A rail checking a model's
+ * sum has to render its own the way the tool did or it flags a correct answer:
+ * `evaluate("0.1 + 0.2")` is `0.30000000000000004` and the tool said `0.3`.
+ */
+export { evaluate, exact } from "./builtin/calculate/index.js";
 export { between, parseDate, shift, type Unit } from "./builtin/date/index.js";
 export { checkUrl } from "./builtin/http/index.js";
 export { readPath } from "./builtin/json/index.js";

package/dist/internals.js

@@ -1 +1 @@
-import{evaluate as e}from"./builtin/calculate/index.js";import{between as p,parseDate as f,shift as m}from"./builtin/date/index.js";import{checkUrl as a}from"./builtin/http/index.js";import{readPath as c}from"./builtin/json/index.js";import{invokeTool as s}from"./bus/invoke.js";import{warnOnOverlap as v}from"./bus/overlap.js";import{scorerFor as T}from"./bus/score.js";import{selectTools as k}from"./bus/select.js";import{toStep as b}from"./bus/step.js";import{newTrace as u}from"./bus/trace.js";export{p as between,a as checkUrl,e as evaluate,s as invokeTool,u as newTrace,f as parseDate,c as readPath,T as scorerFor,k as selectTools,m as shift,b as toStep,v as warnOnOverlap};
+import{evaluate as o,exact as t}from"./builtin/calculate/index.js";import{between as f,parseDate as x,shift as a}from"./builtin/date/index.js";import{checkUrl as c}from"./builtin/http/index.js";import{readPath as n}from"./builtin/json/index.js";import{invokeTool as h}from"./bus/invoke.js";import{warnOnOverlap as w}from"./bus/overlap.js";import{scorerFor as i}from"./bus/score.js";import{selectTools as O}from"./bus/select.js";import{toStep as d}from"./bus/step.js";import{newTrace as D}from"./bus/trace.js";export{f as between,c as checkUrl,o as evaluate,t as exact,h as invokeTool,D as newTrace,x as parseDate,n as readPath,i as scorerFor,O as selectTools,a as shift,d as toStep,w as warnOnOverlap};

package/dist/memories/client.d.ts

@@ -0,0 +1,91 @@
+import type { RootContextId } from "./context.js";
+import type { Recaller } from "./deep-recall/deep-recall.js";
+export type MemorySource = "policy" | "verified" | "tool" | "document" | "user" | "assistant" | "derived" | "system";
+export type MomentSource = "policy" | "verified" | "tool" | "turn";
+export type MemoryKind = "fact" | "decision" | "constraint" | "feedback" | "observation";
+export interface MemoryContext {
+    context_id: string;
+    context_type: string;
+    context_name: string;
+    reference_count: number;
+}
+export interface RecalledItem {
+    locus_id: string;
+    context_ids: string[];
+    text: string;
+    score: number;
+    source?: string;
+    kind?: string;
+    created?: number;
+}
+export interface MemoryClient extends Recaller {
+    retrieveMemories(query: {
+        query: string;
+        graphId?: string;
+        limit?: number;
+        contextIds?: string[];
+        boostContextIds?: string[];
+        sources?: string[];
+        format?: string;
+    }): Promise<{
+        items_found: number;
+        items?: RecalledItem[];
+    }>;
+    storeEventsBatch(items: {
+        event_kind: string;
+        context_id?: string;
+        source?: MemorySource;
+        extends?: string[];
+        related_to?: string[];
+        reinforces?: string[];
+        contradicts?: string[];
+        payload: Record<string, unknown>;
+    }[], graphId?: string): Promise<{
+        stored: number;
+        filtered: number;
+        failed: number;
+        results: {
+            status: "recorded" | "filtered" | "error";
+            event_id?: string;
+            relevance?: "high" | "medium" | "low";
+            error?: string;
+        }[];
+    }>;
+    searchContexts(query: string, graphId?: string, options?: {
+        context_type?: string;
+        page_size?: number;
+        include?: string;
+        format?: string;
+    }): Promise<{
+        contexts: MemoryContext[];
+        total: number;
+        relationships_text?: string;
+    }>;
+    listContextTypes(graphId?: string): Promise<{
+        context_types: {
+            context_type: string;
+            count: number;
+        }[];
+        total: number;
+    }>;
+    getContextGraph(options: {
+        graphId?: string;
+        contextType: string;
+        contextName: string;
+        depth?: number;
+    }): Promise<unknown>;
+    observe(request: {
+        graphId?: string;
+        source: MomentSource;
+        payload: string | Record<string, unknown>;
+        stream?: string;
+        observedAt?: number;
+    }): Promise<{
+        observed: boolean;
+    }>;
+}
+export interface MemoryGraph {
+    client: MemoryClient;
+    graphId?: string;
+    rootContextId?: RootContextId;
+}

package/dist/memories/context.d.ts

@@ -0,0 +1,5 @@
+export declare function contextId(raw: string, defaultType?: string): string;
+export declare const contextIds: (raw: string[] | undefined, defaultType?: string) => string[] | undefined;
+export type RootContextId = string | (() => string | undefined);
+export declare function rootOf(rootContextId: RootContextId | undefined): string | undefined;
+export declare const fixedRoot: (rootContextId: RootContextId | undefined) => string | undefined;

package/dist/memories/context.js

@@ -0,0 +1 @@
+const r="topic",f=120,c=e=>e.toLowerCase().replace(/[^a-z0-9]+/g,"_").replace(/^_+|_+$/g,"");function o(e,n=r){const t=e.indexOf(":"),i=c(t<0?n:e.slice(0,t)),s=c(t<0?e:e.slice(t+1));if(!s)throw new Error(`"${e}" names no context; write it as type:name, like person:alice.`);return`${i}:${s}`.slice(0,120)}const p=(e,n)=>e?.length?e.map(t=>o(t,n)):void 0;function u(e){if(e===void 0)return;const n=typeof e=="function"?e():e;if(!n)throw new Error("No root context id is set for this run, so memory stays closed.");return o(n)}const d=e=>typeof e=="string"?o(e):void 0;export{o as contextId,p as contextIds,d as fixedRoot,u as rootOf};

package/dist/{builtin → memories}/deep-recall/deep-recall.d.ts

@@ -1,3 +1,4 @@
+import { type RootContextId } from "../context.js";
 /** One piece of evidence, with where it came from. */
 export interface RecalledFact {
     text: string;
@@ -41,6 +42,8 @@ export interface DeepRecallOptions {
     client: Recaller;
     /** Graph the walk runs over. Unset, the client's own default is used. */
     graphId?: string;
+    /** Context the walk starts from, fixed or read from run state on each call. */
+    rootContextId?: RootContextId;
     /** Longest evidence list handed back. Default 20. */
     maxFacts?: number;
 }

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

@@ -0,0 +1 @@
+import{tool as c}from"../../tool/index.js";import{rootOf as d}from"../context.js";const l=20;function h(t){const o=t.maxFacts??l;return c({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",needs:["recall"],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."}],costOf:a=>a.costMicroUsd,run:async({question:a,context_ids:r})=>{const n=d(t.rootContextId),s=n?[...new Set([n,...r??[]])]:r,e=await t.client.deepRecall({question:a,...t.graphId?{graphId:t.graphId}:{},...s?.length?{contextIds:s}:{}});return{summary:e.summary,facts:e.facts.slice(0,o),truncated:e.facts.length>o,contextsWalked:e.contexts_walked,coverage:e.coverage,fallback:e.fallback,costMicroUsd:Math.round(e.usage.cost_usd*1e6)}}})}export{h as deepRecall};

package/dist/memories/explore/explore.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryGraph } from "../client.js";
+export interface ExploreOptions extends MemoryGraph {
+    limit?: number;
+    depth?: number;
+}
+export declare function exploreMemory(opts: ExploreOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "query";
+    readonly type: "string";
+    readonly required: false;
+    readonly maxLength: 200;
+    readonly description: "Part of a context name, like pric or alice. Leave out to list what is there.";
+}, {
+    readonly name: "type";
+    readonly type: "string";
+    readonly required: false;
+    readonly maxLength: 60;
+    readonly description: "Only contexts of this type, like person or decision.";
+}]>>;

package/dist/memories/explore/explore.js

@@ -0,0 +1,7 @@
+import{tool as f}from"../../tool/index.js";import{fixedRoot as g,rootOf as y}from"../context.js";import{drawSubgraph as w,readSubgraph as _}from"./subgraph.js";const d=20,$=3,L=t=>`${t} note${t===1?"":"s"}`,l=t=>t.length===0?"Memory is empty: no contexts yet.":`Context types: ${t.map(e=>`${e.context_type} (${e.count})`).join(", ")}.`,m=t=>t.map(e=>`- ${e.context_id} (${L(e.reference_count)})`).join(`
+`),I=t=>{const e=new Map;for(const o of t)e.set(o.context_type,(e.get(o.context_type)??0)+1);return[...e].map(([o,r])=>({context_type:o,count:r}))},C=(t,e,o)=>t.filter(r=>!o||r.context_type===o).filter(r=>!e||r.context_id.toLowerCase().includes(e.toLowerCase())),p=t=>`No contexts match "${t}". Try a shorter stem, or no query to list the types.`;function M(t){const e=t.rootContextId!==void 0,o=g(t.rootContextId)??"your root",r=e?`Shows what is filed under ${o} and how it links up, without reading the notes themselves. With no query it lists the contexts in that subtree and their links. With a query it narrows to the contexts whose name contains it.`:"Shows what is filed in your own memory and how it links up, without reading the notes themselves. With no query it lists the context types in use, which is how to learn the filing scheme before you remember something. With a query it finds matching contexts and draws their relationships.",x=async(n,i,s)=>{const c=n.indexOf(":"),a=_(await t.client.getContextGraph({contextType:n.slice(0,c),contextName:n.slice(c+1),depth:t.depth??$,...t.graphId?{graphId:t.graphId}:{}})),h=C(a.nodes,i,s).slice(0,t.limit??d);return h.length===0?i?p(i):`Nothing is filed under ${n} yet.`:`${l(I(h))}
+
+${w(h,a.edges)}`},u=async(n,i)=>{if(!n?.trim()){const a=await t.client.listContextTypes(t.graphId);return l(a.context_types)}const s=await t.client.searchContexts(n,t.graphId,{page_size:t.limit??d,include:"relationships",format:"mindmap",...i?{context_type:i}:{}});if(s.contexts.length===0)return p(n);const c=s.relationships_text?.trim();return c?`${m(s.contexts)}
+
+Links:
+${c}`:m(s.contexts)};return f({name:"explore_memory",effect:"readonly",description:r,args:[{name:"query",type:"string",required:!1,maxLength:200,description:"Part of a context name, like pric or alice. Leave out to list what is there."},{name:"type",type:"string",required:!1,maxLength:60,description:"Only contexts of this type, like person or decision."}],run:({query:n,type:i})=>{const s=y(t.rootContextId);return s?x(s,n?.trim(),i):u(n?.trim(),i)}})}export{M as exploreMemory};

package/dist/memories/explore/subgraph.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryContext } from "../client.js";
+export interface SubgraphEdge {
+    from: string;
+    to: string;
+    link_type: string;
+}
+export interface Subgraph {
+    nodes: MemoryContext[];
+    edges: SubgraphEdge[];
+}
+export declare function readSubgraph(raw: unknown): Subgraph;
+export declare const drawSubgraph: (nodes: MemoryContext[], edges: SubgraphEdge[]) => string;

package/dist/memories/explore/subgraph.js

@@ -0,0 +1,3 @@
+const c=t=>typeof t=="object"&&t!==null,o=t=>typeof t=="string"?t:"",s=t=>{if(!c(t)||typeof t.context_id!="string")return null;const n=t.context_id.indexOf(":");return{context_id:t.context_id,context_type:o(t.context_type)||t.context_id.slice(0,n),context_name:o(t.context_name)||t.context_id.slice(n+1),reference_count:typeof t.reference_count=="number"?t.reference_count:0}},d=t=>{if(!c(t))return null;const n=o(t.from)||o(t.from_context_id),e=o(t.to)||o(t.to_context_id);return n&&e?{from:n,to:e,link_type:o(t.link_type)||"related_to"}:null};function p(t){const n=c(t)&&c(t.graph)?t.graph:t;if(!c(n))return{nodes:[],edges:[]};const e=Array.isArray(n.nodes)?n.nodes.map(s):[],i=Array.isArray(n.edges)?n.edges.map(d):[];return{nodes:e.filter(r=>r!==null),edges:i.filter(r=>r!==null)}}const _={extends:"extended_by",reinforces:"reinforced_by",contradicts:"contradicted_by",related_to:"related_to"},f=(t,n)=>[...n.filter(e=>e.from===t).map(e=>`${e.link_type} \u2192 ${e.to}`),...n.filter(e=>e.to===t).map(e=>`${_[e.link_type]??e.link_type} \u2190 ${e.from}`)],l=t=>t.map((n,e)=>`  ${e===t.length-1?"\u2514\u2500":"\u251C\u2500"} ${n}`),x=(t,n)=>t.map(e=>[e.context_id,...l(f(e.context_id,n))].join(`
+`)).join(`
+`);export{x as drawSubgraph,p as readSubgraph};

package/dist/memories/index.d.ts

@@ -0,0 +1,30 @@
+import type { Tool } from "../types/index.js";
+import type { MemoryClient, MemorySource } from "./client.js";
+import type { RootContextId } from "./context.js";
+import { type Observer } from "./observe/observe.js";
+import { type RecallFormat } from "./recall/recall.js";
+export type { MemoryClient, MemoryContext, MemoryGraph, MemoryKind, MemorySource, MomentSource, } from "./client.js";
+export { contextId, type RootContextId } from "./context.js";
+export { type DeepRecallOptions, deepRecall, type RecalledFact, type Recaller, type RecallResult, } from "./deep-recall/index.js";
+export { type ExploreOptions, exploreMemory } from "./explore/explore.js";
+export { type Moment, type Observer, type ObserverOptions, observer, } from "./observe/observe.js";
+export { type RecallFormat, type RecallOptions, recall } from "./recall/recall.js";
+export { type RememberOptions, remember } from "./remember/remember.js";
+export interface MemoriesOptions {
+    client: MemoryClient;
+    graphId?: string;
+    rootContextId?: RootContextId;
+    source?: MemorySource;
+    defaultContextType?: string;
+    recallFormat?: RecallFormat;
+    recallLimit?: number;
+    /** Let `recall` say which notes a later one superseded. See `RecallOptions`. */
+    supersede?: boolean;
+    stream?: string;
+    maxFacts?: number;
+}
+export interface MemorySet {
+    tools: Tool<never>[];
+    observe: Observer;
+}
+export declare function memories(opts: MemoriesOptions): MemorySet;

package/dist/memories/index.js

@@ -0,0 +1 @@
+import{deepRecall as a}from"./deep-recall/index.js";import{exploreMemory as l}from"./explore/explore.js";import{observer as c}from"./observe/observe.js";import{recall as n}from"./recall/recall.js";import{remember as x}from"./remember/remember.js";import{contextId as C}from"./context.js";import{deepRecall as g}from"./deep-recall/index.js";import{exploreMemory as v}from"./explore/explore.js";import{observer as T}from"./observe/observe.js";import{recall as R}from"./recall/recall.js";import{remember as j}from"./remember/remember.js";function s(e){const r={client:e.client,...e.graphId?{graphId:e.graphId}:{},...e.rootContextId!==void 0?{rootContextId:e.rootContextId}:{}},o=e.defaultContextType,t=[n({...r,format:e.recallFormat,limit:e.recallLimit,...e.supersede?{supersede:!0}:{},defaultContextType:o}),a({...r,maxFacts:e.maxFacts}),x({...r,source:e.source,defaultContextType:o}),l(r)],m=c({...r,stream:e.stream});return{tools:t,observe:m}}export{C as contextId,g as deepRecall,v as exploreMemory,s as memories,T as observer,R as recall,j as remember};

package/dist/memories/observe/observe.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryGraph, MomentSource } from "../client.js";
+export type Moment = string | Record<string, unknown>;
+export type Observer = (moment: Moment, source?: MomentSource) => Promise<boolean>;
+export interface ObserverOptions extends MemoryGraph {
+    stream?: string;
+}
+export declare function observer(opts: ObserverOptions): Observer;

package/dist/memories/observe/observe.js

@@ -0,0 +1 @@
+const t="turn";function c(r){return async(e,a=t)=>{const{observed:n}=await r.client.observe({source:a,payload:e,...r.graphId?{graphId:r.graphId}:{},...r.stream?{stream:r.stream}:{}});return n}}export{c as observer};

package/dist/memories/recall/recall.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryGraph } from "../client.js";
+import { type RecallFormat } from "./render.js";
+export type { RecallFormat } from "./render.js";
+export interface RecallOptions extends MemoryGraph {
+    format?: RecallFormat;
+    limit?: number;
+    sources?: string[];
+    defaultContextType?: string;
+    /**
+     * Say which notes a later one superseded, rather than returning both flat.
+     *
+     * `remember` takes a `contradicts` link, and without this nothing downstream
+     * ever reads it: a recall hands back the old plan and the new plan as two
+     * rows in score order, and the model answers with whichever scored higher.
+     * The graph knew which one won; the answer did not.
+     *
+     * Off by default because it costs a second read — the subtree under
+     * `rootContextId` — on every recall, and because it needs that root to have
+     * a subtree to read. Without a root there is nothing to fetch and the column
+     * is left off rather than filled with blanks.
+     */
+    supersede?: boolean;
+}
+export declare function recall(opts: RecallOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: "What you want to know, in a sentence.";
+}, {
+    readonly name: "context_ids";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: string;
+}, {
+    readonly name: "limit";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1;
+    readonly max: 50;
+    readonly description: `Most notes to return. Default ${number}.`;
+}]>>;