@carlonicora/nestjs-neo4jsonapi 8.11.1 → 8.12.0

package/dist/agents/drift/nodes/followup.node.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"followup.node.service.js","sourceRoot":"","sources":["../../../../src/agents/drift/nodes/followup.node.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,2CAA+C;AAC/C,6BAAwB;AAExB,wEAAoE;AACpE,oFAAmF;AACnF,2GAAuG;AAEvG,sEAA2E;AAE9D,QAAA,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBpC,CAAC;AAEF,MAAM,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC;IACxF,mBAAmB,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IAChH,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CAClF,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3B,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACnE,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IACjF,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACpF,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;CAC3F,CAAC,CAAC;AAGI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAI9B,YACmB,UAAsB,EACtB,mBAAwC,EACxC,MAAyB,EACzB,aAAiD;QAHjD,eAAU,GAAV,UAAU,CAAY;QACtB,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,WAAM,GAAN,MAAM,CAAmB;QACzB,kBAAa,GAAb,aAAa,CAAoC;QANnD,wBAAmB,GAAG,CAAC,CAAC;QAQvC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAyB,SAAS,CAAC,CAAC;QAC1E,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,aAAa,IAAI,6BAAqB,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAA4C;QACxD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACzB,MAAM,YAAY,GAAG,KAAK,CAAC,oBAAoB,CAAC;QAChD,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QAExC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,sCAAsC,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,aAAa,YAAY,EAAE,EACnH,qBAAqB,CACtB,CAAC;QAEF,0DAA0D;QAC1D,IAAI,YAAY,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC;YACnD,4FAA4F;YAC5F,MAAM,mBAAmB,GAAG,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;YAEnF,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,YAAY,GAAG,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACxE,qDAAqD;gBACrD,OAAO;oBACL,IAAI,EAAE,CAAC;oBACP,iBAAiB,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAC;oBACzE,oBAAoB,EAAE,CAAC;oBACvB,YAAY,EAAE,YAAY,GAAG,CAAC;oBAC9B,QAAQ,EAAE,UAAU;iBACrB,CAAC;YACJ,CAAC;YAED,+BAA+B;YAC/B,OAAO;gBACL,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,WAAW;aACtB,CAAC;QACJ,CAAC;QAED,qCAAqC;QACrC,MAAM,eAAe,GAAG,KAAK,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAC9D,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtG,MAAM,WAAW,GAAgC;YAC/C,gBAAgB,EAAE,KAAK,CAAC,QAAQ;YAChC,gBAAgB,EAAE,eAAe;YACjC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,gBAAgB;SACjB,CAAC;QAEF,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAA+B;YAC3E,WAAW,EAAE,WAAW;YACxB,WAAW,EAAE,WAAW;YACxB,YAAY,EAAE,YAAY;YAC1B,aAAa,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC;YAClC,oBAAoB,EAAE,IAAI;YAC1B,WAAW,EAAE,GAAG;YAChB,uEAAuE;YACvE,uDAAuD;YACvD,GAAG,IAAA,6CAAyB,EAAC,KAAK,CAAC;SACpC,CAAC,CAAC;QAEH,qCAAqC;QACrC,MAAM,cAAc,GAAmB;YACrC,QAAQ,EAAE,eAAe;YACzB,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,KAAK,EAAE,YAAY;YACnB,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;YACpD,cAAc,EAAE,WAAW,CAAC,cAAc;SAC3C,CAAC;QAEF,wCAAwC;QACxC,MAAM,mBAAmB,GAAG,GAAG,KAAK,CAAC,YAAY,UAAU,eAAe,QAAQ,WAAW,CAAC,MAAM,EAAE,CAAC;QAEvG,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,8CAA8C,WAAW,CAAC,mBAAmB,CAAC,MAAM,uBAAuB,EAC3G,qBAAqB,CACtB,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,CAAC;YACP,eAAe,EAAE,CAAC,cAAc,CAAC;YACjC,YAAY,EAAE,mBAAmB;YACjC,oBAAoB,EAAE,YAAY,GAAG,CAAC;YACtC,MAAM,EAAE,WAAW,CAAC,UAAU;YAC9B,QAAQ,EAAE,UAAU,EAAE,iCAAiC;SACxD,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,0BAA0B,CAAC,eAAiC;QAClE,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnE,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,sBAAsB,CAAC,YAAsB;QACzD,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,KAAK,MAAM,WAAW,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;gBACvE,IAAI,CAAC,SAAS;oBAAE,SAAS;gBAEzB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;gBAClF,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;gBAE1F,MAAM,aAAa,GAAG,OAAO;qBAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACT,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACxD,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC;gBACjC,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBAEd,MAAM,mBAAmB,GACvB,aAAa,CAAC,MAAM,GAAG,CAAC;oBACtB,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,WAAW,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;oBAClF,CAAC,CAAC,+BAA+B,CAAC;gBAEtC,OAAO,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,IAAI,iBAAiB,aAAa,uBAAuB,mBAAmB,EAAE,CAAC,CAAC;YAC/G,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,WAAW,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YACzG,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,CAAC;CACF,CAAA;AAhJY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAMoB,wBAAU;QACD,0CAAmB;QAChC,mCAAiB;QACV,sBAAa;GARpC,mBAAmB,CAgJ/B"}
+{"version":3,"file":"followup.node.service.js","sourceRoot":"","sources":["../../../../src/agents/drift/nodes/followup.node.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,2CAA+C;AAC/C,6BAAwB;AAExB,wEAAoE;AACpE,oFAAmF;AACnF,2GAAuG;AAEvG,sEAA2E;AAE9D,QAAA,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBpC,CAAC;AAEF,MAAM,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC;IACxF,mBAAmB,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IAChH,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CAClF,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3B,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACnE,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IACjF,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACpF,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;CAC3F,CAAC,CAAC;AAGI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAI9B,YACmB,UAAsB,EACtB,mBAAwC,EACxC,MAAyB,EACzB,aAAiD;QAHjD,eAAU,GAAV,UAAU,CAAY;QACtB,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,WAAM,GAAN,MAAM,CAAmB;QACzB,kBAAa,GAAb,aAAa,CAAoC;QANnD,wBAAmB,GAAG,CAAC,CAAC;QAQvC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAyB,SAAS,CAAC,CAAC;QAC1E,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,aAAa,IAAI,6BAAqB,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAA4C;QACxD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACzB,MAAM,YAAY,GAAG,KAAK,CAAC,oBAAoB,CAAC;QAChD,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QAExC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,sCAAsC,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,aAAa,YAAY,EAAE,EACnH,qBAAqB,CACtB,CAAC;QAEF,0DAA0D;QAC1D,IAAI,YAAY,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC;YACnD,4FAA4F;YAC5F,MAAM,mBAAmB,GAAG,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;YAEnF,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,YAAY,GAAG,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACxE,qDAAqD;gBACrD,OAAO;oBACL,IAAI,EAAE,CAAC;oBACP,iBAAiB,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAC;oBACzE,oBAAoB,EAAE,CAAC;oBACvB,YAAY,EAAE,YAAY,GAAG,CAAC;oBAC9B,QAAQ,EAAE,UAAU;iBACrB,CAAC;YACJ,CAAC;YAED,+BAA+B;YAC/B,OAAO;gBACL,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,WAAW;aACtB,CAAC;QACJ,CAAC;QAED,qCAAqC;QACrC,MAAM,eAAe,GAAG,KAAK,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAC9D,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtG,MAAM,WAAW,GAAgC;YAC/C,gBAAgB,EAAE,KAAK,CAAC,QAAQ;YAChC,gBAAgB,EAAE,eAAe;YACjC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,gBAAgB;SACjB,CAAC;QAEF,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAA+B;YAC3E,WAAW,EAAE,WAAW;YACxB,WAAW,EAAE,WAAW;YACxB,YAAY,EAAE,YAAY;YAC1B,aAAa,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC;YAClC,oBAAoB,EAAE,IAAI;YAC1B,WAAW,EAAE,GAAG;YAChB,uEAAuE;YACvE,uDAAuD;YACvD,GAAG,IAAA,6CAAyB,EAAC,KAAK,CAAC;SACpC,CAAC,CAAC;QAEH,qCAAqC;QACrC,MAAM,cAAc,GAAmB;YACrC,QAAQ,EAAE,eAAe;YACzB,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,KAAK,EAAE,YAAY;YACnB,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;YACpD,cAAc,EAAE,WAAW,CAAC,cAAc;SAC3C,CAAC;QAEF,wCAAwC;QACxC,MAAM,mBAAmB,GAAG,GAAG,KAAK,CAAC,YAAY,UAAU,eAAe,QAAQ,WAAW,CAAC,MAAM,EAAE,CAAC;QAEvG,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,8CAA8C,WAAW,CAAC,mBAAmB,CAAC,MAAM,uBAAuB,EAC3G,qBAAqB,CACtB,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,CAAC;YACP,eAAe,EAAE,CAAC,cAAc,CAAC;YACjC,YAAY,EAAE,mBAAmB;YACjC,oBAAoB,EAAE,YAAY,GAAG,CAAC;YACtC,MAAM,EAAE,WAAW,CAAC,UAAU;YAC9B,QAAQ,EAAE,UAAU,EAAE,iCAAiC;SACxD,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,0BAA0B,CAAC,eAAiC;QAClE,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnE,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,sBAAsB,CAAC,YAAsB;QACzD,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,KAAK,MAAM,WAAW,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;gBAChF,IAAI,CAAC,SAAS;oBAAE,SAAS;gBAEzB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;gBAClF,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;gBAE1F,MAAM,aAAa,GAAG,OAAO;qBAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACT,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACxD,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC;gBACjC,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBAEd,MAAM,mBAAmB,GACvB,aAAa,CAAC,MAAM,GAAG,CAAC;oBACtB,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,WAAW,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;oBAClF,CAAC,CAAC,+BAA+B,CAAC;gBAEtC,OAAO,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,IAAI,iBAAiB,aAAa,uBAAuB,mBAAmB,EAAE,CAAC,CAAC;YAC/G,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,WAAW,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YACzG,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,CAAC;CACF,CAAA;AAhJY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAMoB,wBAAU;QACD,0CAAmB;QAChC,mCAAiB;QACV,sBAAa;GARpC,mBAAmB,CAgJ/B"}

package/dist/agents/graph/prompts/graph.node.system.prompt.d.ts

@@ -1,5 +1,22 @@
 import { GraphNodeDomainPrompts } from "../../../config/interfaces/config.prompts.interface";
-export declare const GRAPH_NODE_SYSTEM_PROMPT_BASE = "# Role\n\n{DOMAIN_ROLE}\n\nThe data is stored as a graph \u2014 entities are nodes, and the connections between them are edges.\n\nYou answer the user's questions by traversing this graph: find the entities the question is about, read their fields, and walk the relationships between them to reach related entities, continuing until you have enough information to answer. Nearly every useful answer requires following at least one edge \u2014 a single search is rarely the whole story.\n\nEvery fact in your answer must come from a tool call that returned it. Do not invent field names, relationship names, entity types, or record contents.\n\n## Your data\n\n{GRAPH_MAP}\n\nThe list above is the complete inventory of entity types available to you \u2014 anything not listed does not exist. Each entry shows only the type and a one-line description; fields and relationships are not included here. To learn the fields and relationships of any type, call `describe_entity({ type })` \u2014 its response is the only authoritative source for that type's schema. Do not assume a field or relationship exists until `describe_entity` confirms it.\n\nA field marked `money` in the catalogue above is stored as an integer in minor units; its marker states how many decimals (e.g. `total_amount (number, money [integer stored in minor units (2 decimals); divide by 10^2 to display], ...)`). For these fields, every record returned by `read_entity`, `search_entities`, or `traverse` also carries a sibling `<name>_formatted` string \u2014 quote that string when narrating the value in your answer, and never quote the raw integer as if it were the display amount. Filters and sort still target the raw field, in minor units.\n\n{DOMAIN_DATA_CONVENTIONS}\n\n## Tools\n\nYou have five tools.\n\n**Never ask the user a clarifying question.** The user expects an answer, not a follow-up. After `resolve_entity` returns at least one usable candidate, immediately continue: `describe_entity` \u2192 `search_entities` / `traverse` / `read_entity` \u2192 answer. Do not stop the tool chain to confirm what to do next. If multiple candidates of different types could match, pick the one whose type and connected relationships best fit the user's question. State the assumption you made in the `reason` clause of the entity you return; do not ask the user.\n\n{DOMAIN_DISAMBIGUATION}\n\nBefore choosing a tool, check the \"Entities already in this conversation\" block that may be provided below. If the user's phrase refers to an entity listed there \u2014 by its exact name, by a partial name, or implicitly (\"them\", \"their\", \"other\", \"these\") \u2014 treat that entity as resolved. Use its `type` and `id` directly with `read_entity` or `traverse`. **A previous-turn record's nested relationships also carry their own `{ type, id }` \u2014 those ids are addressable, so call `read_entity` or `traverse` with them directly.** Do not call `resolve_entity` for a name that is already resolved in context, and do not call `resolve_entity` for a record whose id you already have.\n\nOtherwise, if the user names an entity \u2014 a person, a place, an organisation, a project, anything that could correspond to a record in the graph \u2014 your first tool call is `resolve_entity` with the user's literal phrase. Do not guess a type. `resolve_entity` returns candidates across every entity type in one shot; you then pick a candidate and proceed with `describe_entity` + the typed tools.\n\nSome entities in the catalog are marked `(bridge \u2192 \u2026)` in the type index. A bridge is a junction record whose own fields are minimal \u2014 the actionable data lives on the relationships named in the bridge marker. When `traverse`, `read_entity`, or `search_entities` returns a record of a bridge type, the response already contains those relationships' targets inlined as nested objects, alongside a `__materialised: [...]` array listing which keys were filled. Do not call `traverse` on a relationship that already appears in `__materialised` \u2014 its content is already in front of you. If a relationship is in the bridge's `materialiseTo` per `describe_entity` but missing from `__materialised`, the target is gated by your module access; do not retry that traverse \u2014 narrate the gap to the user.\n\n- `resolve_entity(text)` \u2014 look up nodes by name across every entity type in one call. Pass the user's literal phrase verbatim, including words like \"and\", \"&\", or other punctuation that may be part of a name. The response carries a `matchMode`, `items` sorted by `score` descending, and an optional `recommendation`:\n  - exact, substring or fuzzy \u2192\n    - **If the response carries `recommendation`, follow it.** It surfaces a deterministic rule already applied to the candidates and is more reliable than re-deriving the rule each turn.\n    - Otherwise: if `items[0].summary` equals the user's literal phrase (case-insensitive), `items[0]` is the answer \u2014 pick it without further disambiguation. Words like \"and\", \"&\", or commas inside that phrase are part of the name; never split the phrase into multiple `resolve_entity` calls and never ask the user to clarify between `items[0]` and lower-ranked items just because the phrase looks plural.\n    - Exception: if the response carries a disambiguation field, two or more candidates share the same summary. Do NOT pick items[0], even when its summary equals the user's literal phrase; this overrides the literal-match rule above. Ask the user for court, sezione or type, or call search_entities with those filters.\n    - Otherwise: if `items.length === 1` or `items[0].score - items[1].score \u2265 0.15`, pick `items[0]`.\n    - Otherwise: pick the most plausible candidate by name match and continue traversing \u2014 the question still has to be answered. Do not refuse the user when at least one usable candidate exists.\n  - `semantic` \u2192 same rules, margin \u2265 0.08. The match is approximate; reflect that in the `reason` clause.\n  - `none` \u2192 no record exists; tell the user in your answer and suggest rephrasing.\n\n- `describe_entity(type)` \u2014 inspect one entity type in full: every field with its type, and every relationship with its target type and description. Call this for every type you intend to touch, before searching, reading, or traversing it. The next three tools will refuse to run on a type that has not been described in this turn.\n\n- `search_entities(type, filters?, sort?, limit?)` \u2014 find records of a known type by filter and sort. Use this when you already have the type (from `resolve_entity` or because the user referred to a kind of record without naming a specific one, e.g. \"all records of that type created after a given date\"). `search_entities` does not search by name \u2014 to find a record by name, call `resolve_entity` first. Unlike resolve_entity, the response carries no matchMode: it carries applied ({ filters, sort, limit }), the filters, sort and limit that actually ran, next to items. Read applied before reporting a result, and describe the result in terms of what ran.\n\n- `read_entity(type, id, include?)` \u2014 fetch the full fields of a single node by id. Tool outputs from other tools are summaries; call this to get the complete record before reporting on it. Calling `read_entity` again for a record already returned in full earlier in this conversation is refused with `{ alreadyRead: true }` \u2014 reuse the copy you already have instead of re-reading.\n\n- `traverse(fromType, fromId, relationship, filters?, sort?, limit?)` \u2014 walk one edge from a known node to its connected nodes. The `relationship` must be one listed under the source type in the catalogue. `filters` and `sort` apply to the target node's fields. This is the only way to cross from one entity type to another. A relationship named `related` is polymorphic: it returns records of mixed types linked to the source by mentions or GM-drawn links, each item tagged with its own `type` \u2014 treat each exactly like a `search_entities` result of that type; filters and sort do not apply to it.\n\nA list item from `search_entities` or `traverse` may carry `availableOnRead`: those fields exist on that record and were withheld from the list for size \u2014 call `read_entity` with the item's `type` and `id` to obtain them. A field absent from both `fields` and `availableOnRead` is empty, not withheld.\n\n{DOMAIN_DEPTH}\n\nIf a tool returns `{ error: \"\u2026\" }`, read the message \u2014 it usually lists valid fields or relationships, or tells you to call `describe_entity` first. Pick one of those and call the tool again. Recover within the same turn; do not apologise to the user for a tool error. Never stop on the first error.\n\n## Output\n\nReturn these fields:\n\n- `answer` \u2014 a concise prose reply (2\u20134 sentences for a single record, a markdown bullet list when enumerating) built from the actual field values and traversal results. When you report on a record, use its real field values, not its type name. When you report a money value, quote the `<name>_formatted` string from the record. When you report a date, use the date as it appears in the record.\n\n{DOMAIN_OUTPUT_RULES}\n\n- `entities` \u2014 every entity that contributes to the meaning of your `answer`, as `{ type, id, reason, fields? }`. An entity contributes when it is the subject the user asked about, or a record the answer reports a fact about. `reason` is one short clause explaining that role (for example \"the account the user asked about\", \"one of the records listed in the answer\"). Populate `fields` with the values you quoted in `answer`. Do not include entities you retrieved, inspected, and discarded: a `resolve_entity` call that returned three candidates of which you only used one \u2014 the other two are not entities to return; a `traverse` that walked an edge whose target you did not mention \u2014 not an entity. These entities are persisted and re-loaded as context on the next turn, so polluting them with irrelevant records will cause the next turn to confuse them with the actual subject \u2014 be strict.\n\n- `stop` \u2014 set to `true` once `answer` is complete and `entities` is the matching set.\n";
+export declare const GRAPH_NODE_SYSTEM_PROMPT_BASE = "# Role\n\n{DOMAIN_ROLE}\n\nThe data is stored as a graph \u2014 entities are nodes, and the connections between them are edges.\n\nYou answer the user's questions by traversing this graph: find the entities the question is about, read their fields, and walk the relationships between them to reach related entities, continuing until you have enough information to answer. Nearly every useful answer requires following at least one edge \u2014 a single search is rarely the whole story.\n\nEvery fact in your answer must come from a tool call that returned it. Do not invent field names, relationship names, entity types, or record contents.\n\n## Your data\n\n{GRAPH_MAP}\n\nThe list above is the complete inventory of entity types available to you \u2014 anything not listed does not exist. Each entry shows only the type and a one-line description; fields and relationships are not included here. To learn the fields and relationships of any type, call `describe_entity({ type })` \u2014 its response is the only authoritative source for that type's schema. Do not assume a field or relationship exists until `describe_entity` confirms it.\n\nA field marked `money` in the catalogue above is stored as an integer in minor units; its marker states how many decimals (e.g. `total_amount (number, money [integer stored in minor units (2 decimals); divide by 10^2 to display], ...)`). For these fields, every record returned by `read_entity`, `search_entities`, or `traverse` also carries a sibling `<name>_formatted` string \u2014 quote that string when narrating the value in your answer, and never quote the raw integer as if it were the display amount. Filters and sort still target the raw field, in minor units.\n\n{DOMAIN_DATA_CONVENTIONS}\n\n## Tools\n\nYou have five tools.\n\n**Never ask the user a clarifying question.** The user expects an answer, not a follow-up. After `resolve_entity` returns at least one usable candidate, immediately continue: `describe_entity` \u2192 `search_entities` / `traverse` / `read_entity` \u2192 answer. Do not stop the tool chain to confirm what to do next. If multiple candidates of different types could match, pick the one whose type and connected relationships best fit the user's question. State the assumption you made in the `reason` clause of the entity you return; do not ask the user.\n\n{DOMAIN_DISAMBIGUATION}\n\nBefore choosing a tool, check the \"Entities already in this conversation\" block that may be provided below. If the user's phrase refers to an entity listed there \u2014 by its exact name, by a partial name, or implicitly (\"them\", \"their\", \"other\", \"these\") \u2014 treat that entity as resolved. Use its `type` and `id` directly with `read_entity` or `traverse`. **A previous-turn record's nested relationships also carry their own `{ type, id }` \u2014 those ids are addressable, so call `read_entity` or `traverse` with them directly.** Do not call `resolve_entity` for a name that is already resolved in context, and do not call `resolve_entity` for a record whose id you already have.\n\nOtherwise, if the user names an entity \u2014 a person, a place, an organisation, a project, anything that could correspond to a record in the graph \u2014 your first tool call is `resolve_entity` with the user's literal phrase. Do not guess a type. `resolve_entity` returns candidates across every entity type in one shot; you then pick a candidate and proceed with `describe_entity` + the typed tools.\n\nSome entities in the catalog are marked `(bridge \u2192 \u2026)` in the type index. A bridge is a junction record whose own fields are minimal \u2014 the actionable data lives on the relationships named in the bridge marker. When `traverse`, `read_entity`, or `search_entities` returns a record of a bridge type, the response already contains those relationships' targets inlined as nested objects, alongside a `__materialised: [...]` array listing which keys were filled. Do not call `traverse` on a relationship that already appears in `__materialised` \u2014 its content is already in front of you. If a relationship is in the bridge's `materialiseTo` per `describe_entity` but missing from `__materialised`, the target is gated by your module access; do not retry that traverse \u2014 narrate the gap to the user.\n\n- `resolve_entity(text)` \u2014 look up nodes by name across every entity type in one call. Pass the user's literal phrase verbatim, including words like \"and\", \"&\", or other punctuation that may be part of a name. The response carries a `matchMode`, `items` sorted by `score` descending, and an optional `recommendation`:\n  - exact, substring or fuzzy \u2192\n    - **If the response carries `recommendation`, follow it.** It surfaces a deterministic rule already applied to the candidates and is more reliable than re-deriving the rule each turn.\n    - Otherwise: if `items[0].summary` equals the user's literal phrase (case-insensitive), `items[0]` is the answer \u2014 pick it without further disambiguation. Words like \"and\", \"&\", or commas inside that phrase are part of the name; never split the phrase into multiple `resolve_entity` calls and never ask the user to clarify between `items[0]` and lower-ranked items just because the phrase looks plural.\n    - Exception: if the response carries a disambiguation field, two or more candidates share the same summary. Do NOT pick items[0], even when its summary equals the user's literal phrase; this overrides the literal-match rule above. Ask the user for court, sezione or type, or call search_entities with those filters.\n    - Otherwise: if `items.length === 1` or `items[0].score - items[1].score \u2265 0.15`, pick `items[0]`.\n    - Otherwise: pick the most plausible candidate by name match and continue traversing \u2014 the question still has to be answered. Do not refuse the user when at least one usable candidate exists.\n  - `semantic` \u2192 same rules, margin \u2265 0.08. The match is approximate; reflect that in the `reason` clause.\n  - `none` \u2192 no record exists; tell the user in your answer and suggest rephrasing.\n\n- `describe_entity(type)` \u2014 inspect one entity type in full: every field with its type, and every relationship with its target type and description. Call this for every type you intend to touch, before searching, reading, or traversing it. The next three tools will refuse to run on a type that has not been described in this turn.\n\n- `search_entities(type, filters?, sort?, limit?)` \u2014 find records of a known type by filter and sort. Use this when you already have the type (from `resolve_entity` or because the user referred to a kind of record without naming a specific one, e.g. \"all records of that type created after a given date\"). `search_entities` does not search by name \u2014 to find a record by name, call `resolve_entity` first. Unlike resolve_entity, the response carries no matchMode: it carries applied ({ filters, sort, limit }), the filters, sort and limit that actually ran, next to items. Read applied before reporting a result, and describe the result in terms of what ran.\n\n- `read_entity(type, id, include?)` \u2014 fetch the full fields of a single node by id. Tool outputs from other tools are summaries; call this to get the complete record before reporting on it. Calling `read_entity` again for a record already returned in full earlier in this conversation is refused with `{ alreadyRead: true }` \u2014 reuse the copy you already have instead of re-reading.\n\n- `traverse(fromType, fromId, relationship, filters?, sort?, limit?)` \u2014 walk one edge from a known node to its connected nodes. The `relationship` must be one listed under the source type in the catalogue. `filters` and `sort` apply to the target node's fields. This is the only way to cross from one entity type to another. A relationship named `related` is polymorphic: it returns records of mixed types linked to the source by mentions or GM-drawn links, each item tagged with its own `type` \u2014 treat each exactly like a `search_entities` result of that type; filters and sort do not apply to it.\n\nA list item from `search_entities` or `traverse` may carry `availableOnRead`: those fields exist on that record and were withheld from the list for size \u2014 call `read_entity` with the item's `type` and `id` to obtain them. A field absent from both `fields` and `availableOnRead` is empty, not withheld.\n\n{DOMAIN_DEPTH}\n\nIf a tool returns `{ error: \"\u2026\" }`, read the message \u2014 it usually lists valid fields or relationships, or tells you to call `describe_entity` first. Pick one of those and call the tool again. Recover within the same turn; do not apologise to the user for a tool error. Never stop on the first error.\n\n## Output\n\nReturn these fields:\n\n- `answer` \u2014 a concise prose reply (2\u20134 sentences for a single record, a markdown bullet list when enumerating) built from the actual field values and traversal results. When you report on a record, use its real field values, not its type name. When you report a money value, quote the `<name>_formatted` string from the record. When you report a date, use the date as it appears in the record.\n\n{DOMAIN_OUTPUT_RULES}\n\n- `entities` \u2014 every entity that contributes to the meaning of your `answer`, as `{ type, id, reason }`. An entity contributes when it is the subject the user asked about, or a record the answer reports a fact about. `reason` is one short clause explaining that role (for example \"the account the user asked about\", \"one of the records listed in the answer\"). Do not include entities you retrieved, inspected, and discarded: a `resolve_entity` call that returned three candidates of which you only used one \u2014 the other two are not entities to return; a `traverse` that walked an edge whose target you did not mention \u2014 not an entity. These entities are persisted and re-loaded as context on the next turn, so polluting them with irrelevant records will cause the next turn to confuse them with the actual subject \u2014 be strict.\n\n- `stop` \u2014 set to `true` once `answer` is complete and `entities` is the matching set.\n";
+/**
+ * The base text for up-front mode: today's base with the "Your data" paragraph,
+ * the describe_entity Tools entry and the two paragraphs that chain
+ * describe_entity after resolve_entity swapped for their up-front wording. Every
+ * other line is the same as {@link GRAPH_NODE_SYSTEM_PROMPT_BASE}.
+ */
+export declare const GRAPH_NODE_SYSTEM_PROMPT_UPFRONT_BASE: string;
 export declare function describeDomainLayer(domain?: GraphNodeDomainPrompts): string;
-export declare function renderGraphNodeSystemPrompt(graphMap: string, domain?: GraphNodeDomainPrompts): string;
+/**
+ * Renders the graph node's system prompt.
+ *
+ * @param graphMap the one-line type index of the user's readable types.
+ * @param domain the app's domain text for the DOMAIN slots.
+ * @param catalog the compact descriptions of every type in `graphMap`
+ *   (`DescribeEntityTool.renderCatalog`). Given, the prompt says the types are
+ *   already described and describe_entity is not needed for them; absent, the
+ *   prompt is today's, byte for byte (describe every type first).
+ */
+export declare function renderGraphNodeSystemPrompt(graphMap: string, domain?: GraphNodeDomainPrompts, catalog?: string): string;
 //# sourceMappingURL=graph.node.system.prompt.d.ts.map

package/dist/agents/graph/prompts/graph.node.system.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.node.system.prompt.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/prompts/graph.node.system.prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAE7F,eAAO,MAAM,6BAA6B,shUAqEzC,CAAC;AAMF,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAG3E;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAerG"}
+{"version":3,"file":"graph.node.system.prompt.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/prompts/graph.node.system.prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAE7F,eAAO,MAAM,6BAA6B,m9TAqEzC,CAAC;AAiCF;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,QAO8D,CAAC;AAMjH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAG3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAoBR"}

package/dist/agents/graph/prompts/graph.node.system.prompt.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GRAPH_NODE_SYSTEM_PROMPT_BASE = void 0;
+exports.GRAPH_NODE_SYSTEM_PROMPT_UPFRONT_BASE = exports.GRAPH_NODE_SYSTEM_PROMPT_BASE = void 0;
 exports.describeDomainLayer = describeDomainLayer;
 exports.renderGraphNodeSystemPrompt = renderGraphNodeSystemPrompt;
 exports.GRAPH_NODE_SYSTEM_PROMPT_BASE = `# Role
@@ -69,20 +69,70 @@ Return these fields:
 
 {DOMAIN_OUTPUT_RULES}
 
-- \`entities\` — every entity that contributes to the meaning of your \`answer\`, as \`{ type, id, reason, fields? }\`. An entity contributes when it is the subject the user asked about, or a record the answer reports a fact about. \`reason\` is one short clause explaining that role (for example "the account the user asked about", "one of the records listed in the answer"). Populate \`fields\` with the values you quoted in \`answer\`. Do not include entities you retrieved, inspected, and discarded: a \`resolve_entity\` call that returned three candidates of which you only used one — the other two are not entities to return; a \`traverse\` that walked an edge whose target you did not mention — not an entity. These entities are persisted and re-loaded as context on the next turn, so polluting them with irrelevant records will cause the next turn to confuse them with the actual subject — be strict.
+- \`entities\` — every entity that contributes to the meaning of your \`answer\`, as \`{ type, id, reason }\`. An entity contributes when it is the subject the user asked about, or a record the answer reports a fact about. \`reason\` is one short clause explaining that role (for example "the account the user asked about", "one of the records listed in the answer"). Do not include entities you retrieved, inspected, and discarded: a \`resolve_entity\` call that returned three candidates of which you only used one — the other two are not entities to return; a \`traverse\` that walked an edge whose target you did not mention — not an entity. These entities are persisted and re-loaded as context on the next turn, so polluting them with irrelevant records will cause the next turn to confuse them with the actual subject — be strict.
 
 - \`stop\` — set to \`true\` once \`answer\` is complete and \`entities\` is the matching set.
 `;
+/**
+ * Up-front replacement of the "Your data" paragraph that follows the type
+ * index: the full catalog is given here, so the model is not told to describe
+ * each type before touching it.
+ */
+const UPFRONT_DATA_PARAGRAPH = `The list above is the complete inventory of entity types available to you — anything not listed does not exist. The full description of every one of these types follows: its fields and relationships, which fields can be filtered and sorted, and with which operators.
+
+{GRAPH_CATALOG}
+
+These descriptions are the only authoritative source for each type's schema, and every type in the list above counts as already described: search, read and traverse it directly, without a describe_entity call first. Do not assume a field or relationship exists unless its type's description above lists it.`;
+/** Up-front replacement of the describe_entity entry under "Tools". */
+const UPFRONT_DESCRIBE_TOOL_ENTRY = `- describe_entity(type) — returns the description of one entity type. Every type in the inventory is already described in full under "Your data", so it is not needed for those types; use it only for a type whose description you cannot find there.`;
+/** Up-front replacement of the "Never ask the user a clarifying question" paragraph: the tool chain skips describe_entity. */
+const UPFRONT_NO_CLARIFYING_PARAGRAPH = `**Never ask the user a clarifying question.** The user expects an answer, not a follow-up. After resolve_entity returns at least one usable candidate, immediately continue: search_entities / traverse / read_entity → answer. Do not stop the tool chain to confirm what to do next. If multiple candidates of different types could match, pick the one whose type and connected relationships best fit the user's question. State the assumption you made in the reason clause of the entity you return; do not ask the user.`;
+/** Up-front replacement of the resolve_entity paragraph: the candidate's type is already described. */
+const UPFRONT_RESOLVE_PARAGRAPH = `Otherwise, if the user names an entity — a person, a place, an organisation, a project, anything that could correspond to a record in the graph — your first tool call is resolve_entity with the user's literal phrase. Do not guess a type. resolve_entity returns candidates across every entity type in one shot; you then pick a candidate and proceed with the typed tools, using its type's description under "Your data".`;
+const TODAY_DATA_PARAGRAPH = /^The list above is the complete inventory of entity types available to you.*$/m;
+// \x60 is a backtick, kept out of this file's new text.
+const TODAY_DESCRIBE_TOOL_ENTRY = /^- \x60describe_entity\(type\)\x60 .*$/m;
+const TODAY_NO_CLARIFYING_PARAGRAPH = /^\*\*Never ask the user a clarifying question\.\*\*.*$/m;
+const TODAY_RESOLVE_PARAGRAPH = /^Otherwise, if the user names an entity .*$/m;
+function replaceLineOnce(text, line, replacement) {
+    if (!line.test(text))
+        throw new Error(`graph node system prompt: line ${line} not found`);
+    return text.replace(line, () => replacement);
+}
+/**
+ * The base text for up-front mode: today's base with the "Your data" paragraph,
+ * the describe_entity Tools entry and the two paragraphs that chain
+ * describe_entity after resolve_entity swapped for their up-front wording. Every
+ * other line is the same as {@link GRAPH_NODE_SYSTEM_PROMPT_BASE}.
+ */
+exports.GRAPH_NODE_SYSTEM_PROMPT_UPFRONT_BASE = [
+    [TODAY_DATA_PARAGRAPH, UPFRONT_DATA_PARAGRAPH],
+    [TODAY_DESCRIBE_TOOL_ENTRY, UPFRONT_DESCRIBE_TOOL_ENTRY],
+    [TODAY_NO_CLARIFYING_PARAGRAPH, UPFRONT_NO_CLARIFYING_PARAGRAPH],
+    [TODAY_RESOLVE_PARAGRAPH, UPFRONT_RESOLVE_PARAGRAPH],
+].reduce((text, [line, replacement]) => replaceLineOnce(text, line, replacement), exports.GRAPH_NODE_SYSTEM_PROMPT_BASE);
 const DEFAULT_ROLE = "You help a user explore their organisation's data.";
 const DOMAIN_SLOTS = ["role", "depth", "disambiguation", "dataConventions", "outputRules"];
 function describeDomainLayer(domain) {
     const parts = DOMAIN_SLOTS.map((slot) => `${slot}=${domain?.[slot]?.trim() ? "supplied" : "kernel"}`);
     return `graph node domain layer: ${parts.join(" ")}`;
 }
-function renderGraphNodeSystemPrompt(graphMap, domain) {
+/**
+ * Renders the graph node's system prompt.
+ *
+ * @param graphMap the one-line type index of the user's readable types.
+ * @param domain the app's domain text for the DOMAIN slots.
+ * @param catalog the compact descriptions of every type in `graphMap`
+ *   (`DescribeEntityTool.renderCatalog`). Given, the prompt says the types are
+ *   already described and describe_entity is not needed for them; absent, the
+ *   prompt is today's, byte for byte (describe every type first).
+ */
+function renderGraphNodeSystemPrompt(graphMap, domain, catalog) {
     // Function replacements throughout: a string replacement would interpret
     // $&, $`, $' and $n inside app-supplied text and silently mangle the prompt.
-    return exports.GRAPH_NODE_SYSTEM_PROMPT_BASE.replace("{GRAPH_MAP}", () => graphMap ||
+    const base = catalog === undefined ? exports.GRAPH_NODE_SYSTEM_PROMPT_BASE : exports.GRAPH_NODE_SYSTEM_PROMPT_UPFRONT_BASE;
+    const rendered = base
+        .replace("{GRAPH_MAP}", () => graphMap ||
         "(No accessible data — the user has no enabled modules with described entities. Do not attempt any tool calls. Respond politely explaining that you have no data to query.)")
         .replace("{DOMAIN_ROLE}", () => domain?.role?.trim() || DEFAULT_ROLE)
         .replace("{DOMAIN_DATA_CONVENTIONS}", () => domain?.dataConventions?.trim() ?? "")
@@ -90,5 +140,8 @@ function renderGraphNodeSystemPrompt(graphMap, domain) {
         .replace("{DOMAIN_DEPTH}", () => domain?.depth?.trim() ?? "")
         .replace("{DOMAIN_OUTPUT_RULES}", () => domain?.outputRules?.trim() ?? "")
         .replace(/\n{3,}/g, "\n\n");
+    // Filled last, after the blank-line collapse, so the catalog text reaches
+    // the model exactly as rendered.
+    return catalog === undefined ? rendered : rendered.replace("{GRAPH_CATALOG}", () => catalog.trim());
 }
 //# sourceMappingURL=graph.node.system.prompt.js.map

package/dist/agents/graph/prompts/graph.node.system.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph.node.system.prompt.js","sourceRoot":"","sources":["../../../../src/agents/graph/prompts/graph.node.system.prompt.ts"],"names":[],"mappings":";;;AA6EA,kDAGC;AAED,kEAeC;AA/FY,QAAA,6BAA6B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE5C,CAAC;AAEF,MAAM,YAAY,GAAG,oDAAoD,CAAC;AAE1E,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,CAAU,CAAC;AAEpG,SAAgB,mBAAmB,CAAC,MAA+B;IACjE,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IACtG,OAAO,4BAA4B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,SAAgB,2BAA2B,CAAC,QAAgB,EAAE,MAA+B;IAC3F,yEAAyE;IACzE,6EAA6E;IAC7E,OAAO,qCAA6B,CAAC,OAAO,CAC1C,aAAa,EACb,GAAG,EAAE,CACH,QAAQ;QACR,4KAA4K,CAC/K;SACE,OAAO,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC;SACpE,OAAO,CAAC,2BAA2B,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SACjF,OAAO,CAAC,yBAAyB,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SAC9E,OAAO,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SAC5D,OAAO,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SACzE,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"graph.node.system.prompt.js","sourceRoot":"","sources":["../../../../src/agents/graph/prompts/graph.node.system.prompt.ts"],"names":[],"mappings":"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"}

package/dist/agents/graph/services/compact-description.d.ts

@@ -0,0 +1,76 @@
+import type { FieldKind } from "../../../common/interfaces/entity.schema.interface";
+/** One described field, as `describe_entity` builds it. */
+export interface EntityFieldDescription {
+    name: string;
+    type: string;
+    description: string;
+    filterable: boolean;
+    sortable: boolean;
+    /** Filter operators the field accepts; empty when it cannot be filtered. */
+    operators: string[];
+    /** The only values the type's service accepts on this field. */
+    values?: string[];
+    kind?: FieldKind;
+    /** Wire format of a richtext field: read and written as markdown. */
+    format?: "markdown";
+    /** Present only when the type declares a list stage. */
+    stage?: "list" | "detail";
+    /** Present only when the type is writable. */
+    writable?: boolean;
+}
+/** One described relationship, as `describe_entity` builds it. */
+export interface EntityRelationshipDescription {
+    name: string;
+    /** `"*"` for a polymorphic relationship: each result carries its own type. */
+    targetType: string;
+    cardinality: "one" | "many";
+    description: string;
+    /** Present only when the type is writable. */
+    writable?: boolean;
+}
+/** A field filled by the type's service on `read_entity` only. */
+export interface EntityDetailFieldDescription {
+    name: string;
+    type: string;
+    description: string;
+    availableOn: "read_entity";
+}
+/**
+ * Everything `describe_entity` knows about one type: the structured form that
+ * {@link renderCompactDescriptions} turns into text.
+ */
+export interface EntityDescription {
+    type: string;
+    description: string;
+    fields: EntityFieldDescription[];
+    relationships: EntityRelationshipDescription[];
+    detailFields?: EntityDetailFieldDescription[];
+    bridge?: {
+        materialiseTo: string[];
+    };
+}
+/**
+ * Renders type descriptions as compact text for a model to read. Lossless:
+ * every attribute of the structured form survives. Repetition is stated once
+ * in a preamble and referenced by name:
+ * - a description used two or more times (fields, relationships and detail
+ *   fields alike) becomes a shared entry `D<n>`;
+ * - each distinct filter-operator list becomes `O<n>`; a field that cannot be
+ *   filtered shows none;
+ * - flags appear only where they differ from the defaults the guide states.
+ *
+ * Entry names are numbered in content order, never input order, so a type's
+ * block does not change when the input is reordered. The type blocks keep the
+ * input order. Same input, same text.
+ *
+ * `standalone: true` (one `describe_entity` result) prints only the guide
+ * lines the given types use; `standalone: false` (a catalog of many types)
+ * prints the whole guide (bar the lines for marks the builder never produces),
+ * so the conventions read the same whatever types a user can see. The shared
+ * entries are always exactly those the given types reference, so the output
+ * never refers to a part it does not define.
+ */
+export declare function renderCompactDescriptions(descriptions: EntityDescription[], options: {
+    standalone: boolean;
+}): string;
+//# sourceMappingURL=compact-description.d.ts.map

package/dist/agents/graph/services/compact-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-description.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/compact-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oDAAoD,CAAC;AAEpF,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,aAAa,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,aAAa,EAAE,6BAA6B,EAAE,CAAC;IAC/C,YAAY,CAAC,EAAE,4BAA4B,EAAE,CAAC;IAC9C,MAAM,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACtC;AA4CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAyHrH"}

package/dist/agents/graph/services/compact-description.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCompactDescriptions = renderCompactDescriptions;
+/**
+ * Shorter descriptions stay inline even when repeated: a reference to the
+ * shared entry would save next to nothing and cost the reader a lookup.
+ */
+const MIN_SHARED_DESCRIPTION_LENGTH = 20;
+/** The reading guide, one entry per convention. Order is the printed order. */
+const GUIDE = {
+    lines: "Fields: name (type) [marks]: description. Relationships: name -> target type (one or many) [marks]: description.",
+    shared: "see Dn: the shared description Dn below.",
+    filter: "filter On: filterable with the operators of list On below. No filter mark: not filterable.",
+    filterOdd: "filterable, no operators: counts as filterable but accepts no operator. not filterable, operators On: lists operators yet is not filterable.",
+    sort: "Filterable fields are sortable unless marked no sort; other fields are not sortable unless marked sort.",
+    values: "values [...]: the only values accepted.",
+    money: "money(N): an integer in minor units with N decimals (divide by 10^N to display); plain money: 2 decimals.",
+    richtext: "richtext: rich text. markdown: read and written as markdown.",
+    list: "list stage (on a type): search_entities and traverse return only the fields marked list; read_entity returns all.",
+    writable: "writable (on a type): the write tools may set only the fields and relationships marked writable.",
+    polymorphic: "-> *: records of any type; each result carries its own type.",
+    detail: "Detail fields: returned only by the tool in their heading; never filtered, sorted, searched or listed.",
+    bridge: "Bridge, materialiseTo: a junction type; its reads inline the targets of the named relationships.",
+};
+/** Guide lines for marks the description builder never produces today: printed only when a type uses them. */
+const ONLY_WHEN_USED = new Set(["filterOdd"]);
+/** Code-unit order: identical on every machine, whatever the locale. */
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const isWritableType = (d) => d.fields.some((f) => f.writable !== undefined) || d.relationships.some((r) => r.writable !== undefined);
+const hasListStage = (d) => d.fields.some((f) => f.stage !== undefined);
+function moneyMark(kind) {
+    return kind.type === "money" && kind.minorUnits !== undefined ? `money(${kind.minorUnits})` : "money";
+}
+/**
+ * Renders type descriptions as compact text for a model to read. Lossless:
+ * every attribute of the structured form survives. Repetition is stated once
+ * in a preamble and referenced by name:
+ * - a description used two or more times (fields, relationships and detail
+ *   fields alike) becomes a shared entry `D<n>`;
+ * - each distinct filter-operator list becomes `O<n>`; a field that cannot be
+ *   filtered shows none;
+ * - flags appear only where they differ from the defaults the guide states.
+ *
+ * Entry names are numbered in content order, never input order, so a type's
+ * block does not change when the input is reordered. The type blocks keep the
+ * input order. Same input, same text.
+ *
+ * `standalone: true` (one `describe_entity` result) prints only the guide
+ * lines the given types use; `standalone: false` (a catalog of many types)
+ * prints the whole guide (bar the lines for marks the builder never produces),
+ * so the conventions read the same whatever types a user can see. The shared
+ * entries are always exactly those the given types reference, so the output
+ * never refers to a part it does not define.
+ */
+function renderCompactDescriptions(descriptions, options) {
+    // Shared descriptions: counted across every described part of every type.
+    const counts = new Map();
+    const count = (text) => {
+        if (text.length >= MIN_SHARED_DESCRIPTION_LENGTH)
+            counts.set(text, (counts.get(text) ?? 0) + 1);
+    };
+    for (const d of descriptions) {
+        for (const f of d.fields)
+            count(f.description);
+        for (const r of d.relationships)
+            count(r.description);
+        for (const f of d.detailFields ?? [])
+            count(f.description);
+    }
+    const sharedTexts = [...counts.entries()]
+        .filter(([, n]) => n >= 2)
+        .map(([text]) => text)
+        .sort(byCodeUnit);
+    const sharedId = new Map(sharedTexts.map((text, i) => [text, `D${i + 1}`]));
+    const operatorLists = [
+        ...new Set(descriptions.flatMap((d) => d.fields.filter((f) => f.operators.length).map((f) => f.operators.join(", ")))),
+    ].sort(byCodeUnit);
+    const operatorId = new Map(operatorLists.map((list, i) => [list, `O${i + 1}`]));
+    const used = new Set(["lines", "sort"]);
+    const describe = (text) => {
+        const id = sharedId.get(text);
+        if (!id)
+            return text;
+        used.add("shared");
+        return `see ${id}`;
+    };
+    const tail = (marks, text) => `${marks.length ? ` [${marks.join(", ")}]` : ""}${text ? `: ${describe(text)}` : ""}`;
+    const blocks = descriptions.map((d) => {
+        const writableType = isWritableType(d);
+        const listStage = hasListStage(d);
+        const typeMarks = [];
+        if (writableType) {
+            typeMarks.push("writable");
+            used.add("writable");
+        }
+        if (listStage) {
+            typeMarks.push("list stage");
+            used.add("list");
+        }
+        const lines = [`## ${d.type}${typeMarks.length ? ` [${typeMarks.join(", ")}]` : ""}`];
+        if (d.description)
+            lines.push(d.description);
+        if (d.bridge) {
+            lines.push(`Bridge, materialiseTo: ${d.bridge.materialiseTo.join(", ")}`);
+            used.add("bridge");
+        }
+        if (d.fields.length) {
+            lines.push("Fields:");
+            for (const f of d.fields) {
+                const marks = [];
+                const ops = f.operators.length ? operatorId.get(f.operators.join(", ")) : undefined;
+                if (f.filterable && ops) {
+                    marks.push(`filter ${ops}`);
+                    used.add("filter");
+                }
+                else if (f.filterable || ops) {
+                    // Unreachable from describe_entity today; kept so the form stays lossless.
+                    marks.push(f.filterable ? "filterable, no operators" : `not filterable, operators ${ops}`);
+                    used.add("filterOdd");
+                }
+                // Default: sortable exactly when filterable. Only exceptions are marked.
+                if (f.filterable && !f.sortable)
+                    marks.push("no sort");
+                if (!f.filterable && f.sortable)
+                    marks.push("sort");
+                if (f.values?.length) {
+                    marks.push(`values ${JSON.stringify(f.values)}`);
+                    used.add("values");
+                }
+                if (f.kind?.type === "money") {
+                    marks.push(moneyMark(f.kind));
+                    used.add("money");
+                }
+                if (f.kind?.type === "richtext") {
+                    marks.push("richtext");
+                    used.add("richtext");
+                }
+                if (f.format === "markdown") {
+                    marks.push("markdown");
+                    used.add("richtext");
+                }
+                if (f.stage === "list")
+                    marks.push("list");
+                if (f.writable)
+                    marks.push("writable");
+                lines.push(`- ${f.name} (${f.type})${tail(marks, f.description)}`);
+            }
+        }
+        if (d.relationships.length) {
+            lines.push("Relationships:");
+            for (const r of d.relationships) {
+                if (r.targetType === "*")
+                    used.add("polymorphic");
+                lines.push(`- ${r.name} -> ${r.targetType} (${r.cardinality})${tail(r.writable ? ["writable"] : [], r.description)}`);
+            }
+        }
+        if (d.detailFields?.length) {
+            used.add("detail");
+            const where = [...new Set(d.detailFields.map((f) => f.availableOn))].sort(byCodeUnit).join(", ");
+            lines.push(`Detail fields, ${where} only:`);
+            for (const f of d.detailFields)
+                lines.push(`- ${f.name} (${f.type})${tail([], f.description)}`);
+        }
+        return lines.join("\n");
+    });
+    const guide = Object.keys(GUIDE)
+        .filter((key) => used.has(key) || (!options.standalone && !ONLY_WHEN_USED.has(key)))
+        .map((key) => `- ${GUIDE[key]}`);
+    const preamble = ["How to read the type descriptions:", ...guide];
+    if (operatorLists.length) {
+        preamble.push("Operator lists:", ...operatorLists.map((list) => `- ${operatorId.get(list)}: ${list}`));
+    }
+    if (sharedTexts.length) {
+        preamble.push("Shared descriptions:", ...sharedTexts.map((text) => `- ${sharedId.get(text)}: ${text}`));
+    }
+    return [preamble.join("\n"), ...blocks].join("\n\n");
+}
+//# sourceMappingURL=compact-description.js.map

package/dist/agents/graph/services/compact-description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-description.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/compact-description.ts"],"names":[],"mappings":"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"}

package/dist/agents/graph/services/filter-operators.d.ts

@@ -0,0 +1,16 @@
+import type { CatalogField } from "../interfaces/graph.catalog.interface";
+import type { ExternalFilterCapability } from "../../../common/interfaces/external.entity.source.interface";
+/** Operators valid for each catalog field type. A type missing here accepts no operator. */
+export declare const TYPE_TO_OP_ALLOWED: Record<string, Set<string>>;
+/**
+ * The filter capabilities a type's service declares, or `undefined` when it
+ * declares none (records in the app database: the type table applies).
+ */
+export declare function serviceFilterCapabilities(svc: unknown): ExternalFilterCapability[] | undefined;
+/**
+ * The operators a filter on `field` may use. When the service declares
+ * capabilities they win over the type table: exactly the operators listed for
+ * the field, none when it is not listed. Otherwise the operators of the field's type.
+ */
+export declare function allowedFilterOperators(field: CatalogField, capabilities: ExternalFilterCapability[] | undefined): string[];
+//# sourceMappingURL=filter-operators.d.ts.map

package/dist/agents/graph/services/filter-operators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-operators.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/filter-operators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAEV,wBAAwB,EACzB,MAAM,6DAA6D,CAAC;AAMrE,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAM1D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,EAAE,GAAG,SAAS,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,wBAAwB,EAAE,GAAG,SAAS,GACnD,MAAM,EAAE,CAGV"}

package/dist/agents/graph/services/filter-operators.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_TO_OP_ALLOWED = void 0;
+exports.serviceFilterCapabilities = serviceFilterCapabilities;
+exports.allowedFilterOperators = allowedFilterOperators;
+// Lives apart from traverse.tool so describe_entity's description builder can
+// use it and traverse.tool can import that builder without an import cycle.
+// traverse.tool re-exports everything here.
+/** Operators valid for each catalog field type. A type missing here accepts no operator. */
+exports.TYPE_TO_OP_ALLOWED = {
+    string: new Set(["eq", "ne", "in", "like", "isNull", "isNotNull"]),
+    number: new Set(["eq", "ne", "in", "gt", "gte", "lt", "lte", "isNull", "isNotNull"]),
+    boolean: new Set(["eq", "ne", "isNull", "isNotNull"]),
+    date: new Set(["eq", "ne", "gt", "gte", "lt", "lte", "isNull", "isNotNull"]),
+    datetime: new Set(["eq", "ne", "gt", "gte", "lt", "lte", "isNull", "isNotNull"]),
+};
+/**
+ * The filter capabilities a type's service declares, or `undefined` when it
+ * declares none (records in the app database: the type table applies).
+ */
+function serviceFilterCapabilities(svc) {
+    const hook = svc?.filterCapabilities;
+    return typeof hook === "function" ? hook.call(svc) : undefined;
+}
+/**
+ * The operators a filter on `field` may use. When the service declares
+ * capabilities they win over the type table: exactly the operators listed for
+ * the field, none when it is not listed. Otherwise the operators of the field's type.
+ */
+function allowedFilterOperators(field, capabilities) {
+    if (capabilities)
+        return [...(capabilities.find((c) => c.field === field.name)?.operators ?? [])];
+    return Array.from(exports.TYPE_TO_OP_ALLOWED[field.type] ?? []);
+}
+//# sourceMappingURL=filter-operators.js.map

package/dist/agents/graph/services/filter-operators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-operators.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/filter-operators.ts"],"names":[],"mappings":";;;AAuBA,8DAGC;AAOD,wDAMC;AAjCD,8EAA8E;AAC9E,4EAA4E;AAC5E,4CAA4C;AAE5C,4FAA4F;AAC/E,QAAA,kBAAkB,GAAgC;IAC7D,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAClE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACpF,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC5E,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;CACjF,CAAC;AAEF;;;GAGG;AACH,SAAgB,yBAAyB,CAAC,GAAY;IACpD,MAAM,IAAI,GAAI,GAAiD,EAAE,kBAAkB,CAAC;IACpF,OAAO,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CACpC,KAAmB,EACnB,YAAoD;IAEpD,IAAI,YAAY;QAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;IAClG,OAAO,KAAK,CAAC,IAAI,CAAC,0BAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AAC1D,CAAC"}

package/dist/agents/graph/tools/describe-entity.tool.d.ts

@@ -1,14 +1,70 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 import { ToolFactory, ToolCallRecord, UserContext } from "./tool.factory";
+import { EntityDescription } from "../services/compact-description";
+import type { CatalogEntity } from "../interfaces/graph.catalog.interface";
+import type { ExternalFilterCapability } from "../../../common/interfaces/external.entity.source.interface";
 declare const inputSchema: z.ZodObject<{
     type: z.ZodString;
 }, z.core.$strip>;
 export { inputSchema as describeEntityInputSchema };
+/**
+ * The structured description of one catalog type: what the model may filter,
+ * sort, read and write on it. `capabilities` are the filter capabilities of the
+ * type's service (`serviceFilterCapabilities`), `undefined` when it declares none.
+ * Shared by `describe_entity` and the describe-first refusals of the read tools,
+ * so both show the same contract.
+ */
+export declare function describeCatalogEntity(entity: CatalogEntity, capabilities: ExternalFilterCapability[] | undefined): EntityDescription;
+/**
+ * The compact, standalone schema text of one catalog type, exactly as
+ * `describe_entity` returns it. `service` is the type's registered service
+ * (its filter capabilities decide the operators). Carried by the describe-first
+ * refusals of read_entity, search_entities and traverse.
+ */
+export declare function renderEntitySchema(entity: CatalogEntity, service: unknown): string;
+/** What `describe_entity` returns for a known type: the compact, self-contained text form. */
+export interface DescribeEntityResult {
+    type: string;
+    /** `renderCompactDescriptions([description], { standalone: true })`. */
+    schema: string;
+}
+/**
+ * The `describe_entity` tool: the fields, relationships, filter operators and
+ * writable parts of one entity type, returned as `{ type, schema }` where
+ * `schema` is the compact text of {@link renderCompactDescriptions} rendered
+ * standalone (it defines every shared part it refers to). An unknown or
+ * inaccessible type returns the factory's `{ error, suggestion? }` object.
+ *
+ * {@link DescribeEntityTool.buildDescription} returns the structured form, for
+ * callers that render several types together.
+ */
 export declare class DescribeEntityTool {
     private readonly factory;
     constructor(factory: ToolFactory);
     build(ctx: UserContext, recorder: ToolCallRecord[]): DynamicStructuredTool;
-    invoke(input: z.infer<typeof inputSchema>, ctx: UserContext, recorder: ToolCallRecord[]): Promise<unknown>;
+    /** The structured description of `type` for this user, or the factory's error object. */
+    buildDescription(type: string, ctx: UserContext): EntityDescription | {
+        error: string;
+        suggestion?: string;
+    };
+    /**
+     * The compact catalog of every type this user can read, for a caller that
+     * gives the model all descriptions up front (the responder lookup). Types are
+     * sorted by name and rendered together with `{ standalone: false }`, so the
+     * text depends only on `ctx.userModuleIds` and is byte-identical across
+     * calls for the same modules. `types` lists the rendered types (the
+     * pre-described set of {@link UserContext.preDescribedTypes});
+     * `approxTokens` is `Math.ceil(text.length / 4)`.
+     */
+    renderCatalog(ctx: UserContext): {
+        text: string;
+        types: string[];
+        approxTokens: number;
+    };
+    invoke(input: z.infer<typeof inputSchema>, ctx: UserContext, recorder: ToolCallRecord[]): Promise<DescribeEntityResult | {
+        error: string;
+        suggestion?: string;
+    }>;
 }
 //# sourceMappingURL=describe-entity.tool.d.ts.map