@spendgraph/tools 0.5.0 → 0.7.0

package/dist/bus/trace.js

@@ -1,22 +1 @@
-import { toAnthropic, toMarkdown, toOpenAI, } from "../wire/index.js";
-import { toStep } from "./step.js";
-export function newTrace(offered, invoke) {
-    const steps = [];
-    return {
-        offered,
-        anthropic: () => toAnthropic(offered),
-        openai: () => toOpenAI(offered),
-        markdown: (heading) => toMarkdown(offered, heading),
-        effectOf: (name) => offered.find((d) => d.name === name)?.effect,
-        invoke: async (name, args) => {
-            const result = await invoke(name, args);
-            steps.push(toStep(result, steps.length));
-            return result;
-        },
-        steps: () => [...steps],
-        record: () => ({
-            offeredTools: offered.map((d) => d.name),
-            steps: [...steps],
-        }),
-    };
-}
+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

@@ -1,6 +1,18 @@
-export { type ArtifactFormat, answerOf, type ClockOptions, CommissionAbortedError, type CommissionClient, CommissionTimeoutError, calculate, 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, renderDesign, type SearchDepth, think, type WebSearchOptions, type WriteDocumentOptions, webSearch, writeDocument, } from "./builtin/index.js";
-export type { ToolBus, ToolBusOptions, ToolTrace } from "./bus/index.js";
-export { toolbus } from "./bus/index.js";
+/**
+ * What `bus.anthropic()`, `bus.openai()` and `turn.record()` hand back.
+ *
+ * On the main entry because the functions that return them are: naming the
+ * result of a method you called from here should not send you to a second
+ * subpath, or to a second package. `@spendgraph/tools/wire` still holds the
+ * converters themselves, for a caller adapting a declaration by hand.
+ */
+export type { RolloutStep } from "@spendgraph/sdk";
+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,3 +1 @@
-export { answerOf, CommissionAbortedError, CommissionTimeoutError, calculate, currentTime, DEFAULT_DESIGN, dateMath, deepRecall, escalate, finish, httpRequest, isFinished, jsonQuery, mergeDesign, renderDesign, think, webSearch, writeDocument, } from "./builtin/index.js";
-export { toolbus } from "./bus/index.js";
-export { bindTool, ToolDriftError, ToolNotStoredError, tool } from "./tool/index.js";
+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,13 +4,20 @@
  * 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";
 export { invokeTool } from "./bus/invoke.js";
 export { warnOnOverlap } from "./bus/overlap.js";
-export { score } from "./bus/score.js";
+export { type Describable, type Scorer, scorerFor } from "./bus/score.js";
 export { selectTools } from "./bus/select.js";
 export { toStep } from "./bus/step.js";
 export { newTrace } from "./bus/trace.js";

package/dist/internals.js

@@ -1,10 +1 @@
-export { evaluate } from "./builtin/calculate/index.js";
-export { between, parseDate, shift } from "./builtin/date/index.js";
-export { checkUrl } from "./builtin/http/index.js";
-export { readPath } from "./builtin/json/index.js";
-export { invokeTool } from "./bus/invoke.js";
-export { warnOnOverlap } from "./bus/overlap.js";
-export { score } from "./bus/score.js";
-export { selectTools } from "./bus/select.js";
-export { toStep } from "./bus/step.js";
-export { newTrace } from "./bus/trace.js";
+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/memories/deep-recall/deep-recall.d.ts

@@ -0,0 +1,67 @@
+import { type RootContextId } from "../context.js";
+/** One piece of evidence, with where it came from. */
+export interface RecalledFact {
+    text: string;
+    locus: string;
+    contexts: string[];
+    score: number;
+    source?: string;
+}
+/** What a deep recall answered, and what answering it cost. */
+export interface RecallResult {
+    facts: RecalledFact[];
+    contexts_walked: string[];
+    summary?: string;
+    coverage: "full" | "partial";
+    fallback: boolean;
+    usage: {
+        cost_usd: number;
+    };
+}
+/**
+ * Anything that can answer a deep recall — a `LocusGraphClient`, or a test
+ * double.
+ *
+ * Declared structurally rather than imported, for the reason `prompt` declares
+ * its own `Recordable` and `llms` reads provider replies as plain objects: a
+ * type-only import still puts `@locusgraph/client` in `dependencies`, so every
+ * install of this package downloaded a client that nothing here ever loads, and
+ * every consumer's typecheck needed it resolvable to read one `.d.ts`. A real
+ * client satisfies this, which `tests/structural.test.ts` proves with the
+ * package still on hand as a devDependency.
+ */
+export interface Recaller {
+    deepRecall(query: {
+        question: string;
+        graphId?: string;
+        contextIds?: string[];
+    }): Promise<RecallResult>;
+}
+export interface DeepRecallOptions {
+    /** A `LocusGraphClient`, or anything carrying its `deepRecall`. */
+    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;
+}
+/**
+ * Your own knowledge base, answered with cited evidence.
+ *
+ * Cost comes back as micro-USD because deep recall runs model calls of its own,
+ * and that spend is invisible to whatever loop called this.
+ */
+export declare function deepRecall(opts: DeepRecallOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: "One focused question, not a conversation and not several at once.";
+}, {
+    readonly name: "context_ids";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: string;
+}]>>;

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/deep-recall/index.d.ts

@@ -0,0 +1 @@
+export { type DeepRecallOptions, deepRecall, type RecalledFact, type Recaller, type RecallResult, } from "./deep-recall.js";

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

@@ -0,0 +1 @@
+import{deepRecall as o}from"./deep-recall.js";export{o 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.";
+}]>>;

package/dist/memories/remember/remember.js

@@ -0,0 +1 @@
+import{tool as h}from"../../tool/index.js";import{contextId as y,contextIds as a,fixedRoot as x,rootOf as w}from"../context.js";const g=["fact","decision","constraint","feedback","observation"],b="assistant",C=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),q=(e,t)=>{if(t==null)return{data:e};if(!C(t))throw new Error("details must be a JSON object of named fields.");return{...t,data:e}},d=(e,t)=>t?.length?{[e]:t}:{};function v(e){const t=e.defaultContextType,u=e.rootContextId===void 0?"":` under ${x(e.rootContextId)??"your root"}`,m=(c,l)=>{const s=w(e.rootContextId),i=a(l,t)??[],r=s?[s,...i]:i;return[...new Set(r)].filter(n=>n!==c)};return h({name:"remember",effect:"idempotent",description:`Records one thing in your own memory${u} so a later run can recall it. File it under a context named type:name, like person:alice or decision:pricing_tier, reusing a name from explore_memory when one fits. One fact per call; the text should stand on its own without the conversation around it.`,args:[{name:"context",type:"string",required:!0,maxLength:200,description:"Where it is filed, as type:name."},{name:"text",type:"string",required:!0,maxLength:4e3,description:"The thing to remember, as a complete sentence or two."},{name:"kind",type:"enum",required:!1,options:g,description:"What sort of thing it is. Default fact."},{name:"details",type:"json",required:!1,description:"Structured fields worth keeping with the note, as a JSON object: amounts, dates, ids, URLs. The text is still what a recall shows; these ride along with it."},{name:"extends",type:"list",required:!1,description:"Contexts this is a more specific detail of, as type:name."},{name:"related_to",type:"list",required:!1,description:"Contexts this sits alongside, as type:name."},{name:"reinforces",type:"list",required:!1,description:"Contexts this backs up with more evidence, as type:name."},{name:"contradicts",type:"list",required:!1,description:"Contexts this supersedes, as type:name."}],run:async({context:c,text:l,kind:s="fact",details:i,...r})=>{const n=y(c,t),f={event_kind:s,context_id:n,source:e.source??b,payload:q(l,i),...d("extends",m(n,r.extends)),...d("related_to",a(r.related_to,t)),...d("reinforces",a(r.reinforces,t)),...d("contradicts",a(r.contradicts,t))},p=await e.client.storeEventsBatch([f],e.graphId),[o]=p.results;if(!o||o.status==="error")throw new Error(o?.error??"The memory was not stored, and the server did not say why.");return o.status==="filtered"?{stored:!1,context:n,reason:o.error??"judged not worth keeping"}:{stored:!0,context:n,relevance:o.relevance}}})}export{v as remember};

package/dist/search/index.d.ts

@@ -0,0 +1,5 @@
+export type { Recency, SearchAsk, SearchDepth, Searched, Searcher, SearcherOptions, SearchUsage, Source, } from "./search.js";
+export { DEPTHS, NO_TOKENS } from "./search.js";
+export { type SearxngOptions, searxng, textOf } from "./searxng/index.js";
+export { type TavilyOptions, tavily } from "./tavily/index.js";
+export { readReply, type SonarOptions, sonar } from "./sonar/index.js";

package/dist/search/index.js

@@ -0,0 +1 @@
+import{DEPTHS as e,NO_TOKENS as t}from"./search.js";import{searxng as f,textOf as p}from"./searxng/index.js";import{tavily as m}from"./tavily/index.js";import{readReply as l,sonar as n}from"./sonar/index.js";export{e as DEPTHS,t as NO_TOKENS,l as readReply,f as searxng,n as sonar,m as tavily,p as textOf};

package/dist/search/retry.d.ts

@@ -0,0 +1,6 @@
+import type { SearcherOptions } from "./search.js";
+/**
+ * Sends again while the answer is a 429 or a 5xx and tries remain, then hands
+ * back whatever came last, ok or not, for the caller to read or refuse.
+ */
+export declare function retrying(opts: Pick<SearcherOptions, "attempts" | "sleep" | "random">): (send: () => Promise<Response>) => Promise<Response>;

package/dist/search/retry.js

@@ -0,0 +1 @@
+const M=500,f=8e3;function m(t){const r=t.headers.get("retry-after");if(!r)return null;const e=Number(r);return Number.isFinite(e)&&e>=0?e*1e3:null}const u=t=>t===429||t>=500;function A(t){const r=Math.max(1,t.attempts??3),e=t.sleep??(o=>new Promise(n=>setTimeout(n,o))),c=t.random??Math.random;return async o=>{for(let n=1;;n++){const s=await o();if(s.ok||!u(s.status)||n===r)return s;const a=Math.min(8e3,500*2**(n-1)),i=m(s)??a;await e(i+a*c())}}}export{A as retrying};

package/dist/search/search.d.ts

@@ -0,0 +1,63 @@
+/** How much searching one call is worth. */
+export type SearchDepth = "quick" | "pro" | "deep";
+export declare const DEPTHS: readonly SearchDepth[];
+export type Recency = "day" | "week" | "month" | "year";
+export interface Source {
+    url: string;
+    title?: string;
+    date?: string;
+}
+export interface SearchUsage {
+    inputTokens: number;
+    outputTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    searchQueries: number;
+}
+/** What every searcher hands back, whoever did the searching. */
+export interface Searched {
+    answer: string;
+    results: Source[];
+    model: string;
+    truncated: boolean;
+    usage: SearchUsage;
+}
+export interface SearchAsk {
+    query: string;
+    depth: SearchDepth;
+    recency?: Recency;
+}
+export type Searcher = ((ask: SearchAsk) => Promise<Searched>) & {
+    domains?: readonly string[];
+};
+/** What every searcher is configured with; each adds only where its answers come from. */
+export interface SearcherOptions {
+    /** Hosts results are restricted to. Set here, so the model cannot widen it. */
+    domains?: string[];
+    /** Give up on a request after this. */
+    timeoutMs?: number;
+    /** Longest answer handed back. Default 20000 characters. */
+    maxChars?: number;
+    /** Longest source list handed back. Default 20. */
+    maxResults?: number;
+    /**
+     * Tries for a rate limit or a bad minute on the other side. Default 3.
+     *
+     * A wave of sub-questions searches in parallel, so two calls landing together
+     * is ordinary and a 429 on the second is not a failure worth surfacing — it
+     * is a wait. `retry-after` is honoured where the server sends one, and the
+     * wait is spread by up to one backoff on top: a whole wave limited at the
+     * same instant computes the same delay, and retrying in step rebuilds the
+     * burst that caused it.
+     */
+    attempts?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+    /** Injected for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected for tests. Returns 0 to 1, and spreads a retried wave apart. */
+    random?: () => number;
+}
+export declare const DEFAULT_MAX_CHARS = 20000;
+export declare const DEFAULT_MAX_RESULTS = 20;
+export declare const NO_TOKENS: SearchUsage;

package/dist/search/search.js

@@ -0,0 +1 @@
+const o=["quick","pro","deep"],e=2e4,t=20,n={inputTokens:0,outputTokens:0,citationTokens:0,reasoningTokens:0,searchQueries:1};export{e as DEFAULT_MAX_CHARS,t as DEFAULT_MAX_RESULTS,o as DEPTHS,n as NO_TOKENS};

package/dist/search/searxng/index.d.ts

@@ -0,0 +1,2 @@
+export { type SearxngOptions, searxng } from "./searxng.js";
+export { textOf } from "./text.js";

package/dist/search/searxng/index.js

@@ -0,0 +1 @@
+import{searxng as o}from"./searxng.js";import{textOf as x}from"./text.js";export{o as searxng,x as textOf};

package/dist/search/searxng/searxng.d.ts

@@ -0,0 +1,14 @@
+import { type SearchDepth, type Searcher, type SearcherOptions } from "../search.js";
+export interface SearxngOptions extends SearcherOptions {
+    /** The SearXNG instance, such as http://localhost:8080. Required. */
+    baseUrl: string;
+    /** Pin which engines answer. Default: whatever the instance runs. */
+    engines?: string[];
+    /** Pin the language. Default: the instance's own. */
+    language?: string;
+    /** Text kept from each page read. Default 6000 characters. */
+    pageChars?: number;
+    /** Pages read at each depth. Default 5, 8 and 10. */
+    pages?: Partial<Record<SearchDepth, number>>;
+}
+export declare function searxng(opts: SearxngOptions): Searcher;