@spendgraph/tools 0.6.0 → 0.8.0

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/output.d.ts

@@ -1,20 +1,3 @@
-/**
- * What a handler returned, as the string a result carries.
- *
- * A string is itself; anything else is JSON. `graph`'s `stringify` describes
- * this as "the same convention as a tool result" — it was not, and this is the
- * side that had drifted.
- *
- * `JSON.stringify` returns `undefined` for a function or an undefined value, so
- * a completed result carried `output: undefined` where its own type says
- * `string`, and the model was handed nothing while being told it was handed
- * something. And it *throws* on a circular object, a `BigInt`, or anything whose
- * `toJSON` throws — a circular object being any value with a parent backlink.
- *
- * What comes back when a value cannot be written is a note saying so, never
- * `""`: an empty output reads as a tool that produced nothing, and this is a
- * tool that produced something unwritable.
- */
 export declare function render(value: unknown): string;
 /**
  * Why a handler failed, from whatever it threw.

package/dist/bus/output.js

@@ -1,2 +1,2 @@
-function r(n){if(n==null)return"";if(typeof n=="string")return n;try{const t=JSON.stringify(n);return t===void 0?`[not recordable: ${typeof n}]`:t}catch(t){return`[not recordable: ${(t instanceof Error?t.message:String(t)).split(`
-`)[0]}]`}}function o(n){if(n instanceof Error&&n.message.trim())return n.message;if(typeof n=="string"&&n.trim())return n;const t=r(n);return t&&t!=="{}"?`Tool failed: ${t}`:"Tool failed."}export{o as reasonFor,r as render};
+function t(n){const r=n;return typeof r?.answer=="string"&&r.answer.trim()!==""&&Array.isArray(r.results)}function e(n){if(n==null)return"";if(typeof n=="string")return n;if(t(n))return n.answer;try{const r=JSON.stringify(n);return r===void 0?`[not recordable: ${typeof n}]`:r}catch(r){return`[not recordable: ${(r instanceof Error?r.message:String(r)).split(`
+`)[0]}]`}}function o(n){if(n instanceof Error&&n.message.trim())return n.message;if(typeof n=="string"&&n.trim())return n;const r=e(n);return r&&r!=="{}"?`Tool failed: ${r}`:"Tool failed."}export{o as reasonFor,e as render};

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 { 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 PaperSearchOptions, type Publisher, type PublishOptions, paperSearch, 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 { Source } from "./search/search.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{answerOf as o,calculate as t,codeExec as s,currentTime as a,dateMath as i,dates as l,decline as c,declinedFor as n,escalate as d,escalationOf as p,extract as m,finish as f,httpRequest as x,isDeclined as h,isEscalated as u,isFinished as b,jsonFrom as E,jsonQuery as S,notes as T,notesStore as w,openalex as y,paperSearch as F,publish as M,retryAfterMs as O,think as j,webSearch as k,wikidata as D}from"./builtin/index.js";import{busgroup as g,priced as q,spentOn as v,toolbus as A}from"./bus/index.js";import{contextId as N,deepRecall as Q,exploreMemory as z,memories as B,observer as C,recall as G,remember as H}from"./memories/index.js";import{bindTool as K,ToolDriftError as L,ToolNotStoredError as P,tool as U}from"./tool/index.js";export{L as ToolDriftError,P as ToolNotStoredError,o as answerOf,K as bindTool,g as busgroup,t as calculate,s as codeExec,N as contextId,a as currentTime,i as dateMath,l as dates,c as decline,n as declinedFor,Q as deepRecall,d as escalate,p as escalationOf,z as exploreMemory,m as extract,f as finish,x as httpRequest,h as isDeclined,u as isEscalated,b as isFinished,E as jsonFrom,S as jsonQuery,B as memories,T as notes,w as notesStore,C as observer,y as openalex,F as paperSearch,q as priced,M as publish,G as recall,H as remember,O as retryAfterMs,v as spentOn,j as think,U as tool,A as toolbus,k as webSearch,D as wikidata};

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}.`;
+}]>>;

package/dist/memories/recall/recall.js

@@ -0,0 +1 @@
+import{tool as f}from"../../tool/index.js";import{contextIds as l,fixedRoot as h,rootOf as p}from"../context.js";import{readSubgraph as x}from"../explore/subgraph.js";import{rendered as y}from"./render.js";const g="toon",u=10,w=50,I=3;async function T(e,n){if(!e.supersede||!n)return;const o=n.indexOf(":"),s=x(await e.client.getContextGraph({contextType:n.slice(0,o),contextName:n.slice(o+1),depth:I,...e.graphId?{graphId:e.graphId}:{}})),a=new Map;for(const r of s.edges)r.link_type==="contradicts"&&a.set(r.to,r.from);return r=>r.context_ids.map(t=>a.get(t)).find(t=>t!==void 0)}function k(e){const n=e.rootContextId!==void 0,o=h(e.rootContextId)??"your root";return f({name:"recall",effect:"readonly",description:"Searches your own memory for what was recorded about something and returns the matching notes, one per row with the contexts each is filed under. Cheap, so try it before a web search and before deep_recall. Use deep_recall instead when the answer is spread across several notes or needs a why. Ask one focused thing.",args:[{name:"question",type:"string",required:!0,maxLength:1e3,description:"What you want to know, in a sentence."},{name:"context_ids",type:"list",required:!1,description:n?`Contexts under ${o} to favour, as type:name. Take them from an earlier result or from explore_memory.`:"Only search these contexts, as type:name. Take them from an earlier result or from explore_memory."},{name:"limit",type:"number",required:!1,min:1,max:w,description:`Most notes to return. Default ${e.limit??u}.`}],run:async({question:s,context_ids:a,limit:r})=>{const t=p(e.rootContextId),i=l(a,e.defaultContextType),d=t?[t]:i,c=t&&i?i:void 0,m=(await e.client.retrieveMemories({query:s,limit:r??e.limit??u,format:"json",...e.graphId?{graphId:e.graphId}:{},...d?{contextIds:d}:{},...c?{boostContextIds:c}:{},...e.sources?.length?{sources:e.sources}:{}})).items??[];return m.length===0?"Nothing recorded about that.":y(m,e.format??g,await T(e,t))}})}export{k as recall};

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

@@ -0,0 +1,5 @@
+import type { RecalledItem } from "../client.js";
+export type RecallFormat = "toon" | "markdown";
+/** Which context superseded this note's, when one did. */
+export type Superseded = (item: RecalledItem) => string | undefined;
+export declare const rendered: (items: RecalledItem[], format: RecallFormat, by?: Superseded) => string;

package/dist/memories/recall/render.js

@@ -0,0 +1,3 @@
+const t=/[,:"\n\\]|^\s|\s$|^$/,d=n=>t.test(n)?`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\n/g,"\\n")}"`:n,c=n=>String(Math.round(n*100)),$=(n,o,e)=>[n.context_ids.join(";"),n.text,n.source??"",c(n.score),...e?[o??""]:[]],a=(n,o)=>{const e=o?"contexts,text,source,relevance,superseded_by":"contexts,text,source,relevance";return[`memories[${n.length}]{${e}}:`,...n.map(s=>`  ${$(s,o?.(s),o!==void 0).map(d).join(",")}`)].join(`
+`)},p=(n,o)=>n.map(e=>{const s=o?.(e),r=s?` \u2014 superseded by ${s}`:"";return`- [${e.context_ids.join(", ")}] ${e.text} (${e.source??"unknown"}, ${c(e.score)}%)${r}`}).join(`
+`),u=(n,o,e)=>o==="toon"?a(n,e):p(n,e);export{u as rendered};

package/dist/memories/remember/remember.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryGraph, MemorySource } from "../client.js";
+export interface RememberOptions extends MemoryGraph {
+    source?: MemorySource;
+    defaultContextType?: string;
+}
+export declare function remember(opts: RememberOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "context";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 200;
+    readonly description: "Where it is filed, as type:name.";
+}, {
+    readonly name: "text";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 4000;
+    readonly description: "The thing to remember, as a complete sentence or two.";
+}, {
+    readonly name: "kind";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["fact", "decision", "constraint", "feedback", "observation"];
+    readonly description: "What sort of thing it is. Default fact.";
+}, {
+    readonly name: "details";
+    readonly type: "json";
+    readonly required: false;
+    readonly description: string;
+}, {
+    readonly name: "extends";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this is a more specific detail of, as type:name.";
+}, {
+    readonly name: "related_to";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this sits alongside, as type:name.";
+}, {
+    readonly name: "reinforces";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this backs up with more evidence, as type:name.";
+}, {
+    readonly name: "contradicts";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: "Contexts this supersedes, as type:name.";
+}]>>;