@xano/sdk 1.0.15 → 1.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (290) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +33 -37
  3. package/dist/.build-fingerprint +1 -1
  4. package/dist/{agent-file-refresh-ZRGNOA6Q.js → agent-file-refresh-QTFMNYPY.js} +12 -12
  5. package/dist/{agent-skill-command-DV26SDA2.js → agent-skill-command-XZVBG34H.js} +74 -73
  6. package/dist/{answer-shape-AVZSKBR6.js → answer-shape-ZRQS7ZC4.js} +5 -5
  7. package/dist/{backend-dir-NTMXWE5R.js → backend-dir-DCT3T6HP.js} +11 -11
  8. package/dist/{backend-slot-DZAUHLTS.js → backend-slot-7BATLL3X.js} +4 -4
  9. package/dist/bin.js +64 -63
  10. package/dist/{branch-IJTBZZFO.js → branch-SJKKUCMZ.js} +9 -9
  11. package/dist/branch-commands-OEMOFAKC.js +80 -0
  12. package/dist/bundle.d.ts +2 -2
  13. package/dist/bundle.js +15 -69
  14. package/dist/{capture-GW5KNKMB.js → capture-RYBJE25P.js} +5 -5
  15. package/dist/{chunk-3H7R4ISR.js → chunk-2DUYJR5N.js} +2 -2
  16. package/dist/{chunk-MFWF2NZJ.js → chunk-2H5BQRHF.js} +2 -2
  17. package/dist/{chunk-GDJCWQIK.js → chunk-2IC3K22K.js} +12 -8
  18. package/dist/{chunk-O44MJTLR.js → chunk-35SI4GBM.js} +3 -3
  19. package/dist/{chunk-VUWR5YLE.js → chunk-3QQFP3AD.js} +13 -13
  20. package/dist/{chunk-ICK36EGF.js → chunk-4EVDCSEY.js} +2 -2
  21. package/dist/{chunk-GIQIMWTK.js → chunk-4LT5AVHF.js} +14 -14
  22. package/dist/{chunk-AXMUYBWQ.js → chunk-4XGZ325S.js} +3 -3
  23. package/dist/{chunk-JWASCOHO.js → chunk-52QAENY6.js} +14 -14
  24. package/dist/{chunk-2LF734YB.js → chunk-54CJ74BH.js} +4 -4
  25. package/dist/{chunk-ASQX477B.js → chunk-573RRKNT.js} +7 -7
  26. package/dist/{chunk-3GZMP7II.js → chunk-5AVFVC22.js} +38 -22
  27. package/dist/{chunk-IKXXTRMN.js → chunk-64UVVLDT.js} +4 -4
  28. package/dist/{chunk-RBTZEHXF.js → chunk-6DSA6W4O.js} +3 -3
  29. package/dist/{chunk-EQXHUWUO.js → chunk-6FCAFWD5.js} +2 -2
  30. package/dist/{chunk-4MX5LMPQ.js → chunk-6ODQ5GDZ.js} +2 -2
  31. package/dist/{chunk-ZF2CBXT5.js → chunk-7NKC4MBT.js} +3 -3
  32. package/dist/{chunk-Y5XAPLZS.js → chunk-7UQZ7C4W.js} +4 -4
  33. package/dist/{chunk-CJDPSCMX.js → chunk-7ZVQIKNL.js} +3 -3
  34. package/dist/{chunk-FOBVJ2UR.js → chunk-ACFBRMCS.js} +8 -8
  35. package/dist/{chunk-RVAEPPRH.js → chunk-AICWDCLJ.js} +2 -2
  36. package/dist/{chunk-WS4BA75E.js → chunk-AJBOGO5U.js} +4 -4
  37. package/dist/{chunk-AE5CRAKS.js → chunk-ANUBTY3C.js} +8 -8
  38. package/dist/{chunk-UVHSMANV.js → chunk-C6RBLPFY.js} +47 -47
  39. package/dist/{chunk-SHHXLI2K.js → chunk-CNNGNK46.js} +7 -7
  40. package/dist/{chunk-7ZQ73AHJ.js → chunk-CWC6HE66.js} +31 -31
  41. package/dist/{chunk-A2N2C2WD.js → chunk-DNUU4IEM.js} +7 -7
  42. package/dist/{chunk-Q7DGTQ5G.js → chunk-E34VGSCI.js} +2 -1
  43. package/dist/{chunk-YR3MNGWZ.js → chunk-E5M5P23K.js} +8 -8
  44. package/dist/{chunk-HJZUI2ZU.js → chunk-EAZTRU75.js} +2 -2
  45. package/dist/{chunk-KMKUH2IO.js → chunk-EPB6FAR5.js} +5 -5
  46. package/dist/{chunk-B6AFJVG4.js → chunk-ES6FBPLY.js} +5 -5
  47. package/dist/chunk-EUAU4QKI.js +67 -0
  48. package/dist/{chunk-IDOVZLPK.js → chunk-EXJ4Q5F6.js} +2 -2
  49. package/dist/{chunk-FKQX6KU7.js → chunk-F3JK5RIY.js} +2 -2
  50. package/dist/{chunk-W2QFR3ZJ.js → chunk-FIOC7RSU.js} +2 -2
  51. package/dist/{chunk-YEH5OIPF.js → chunk-FMXPV5JI.js} +39 -11
  52. package/dist/{chunk-GVHWIDEJ.js → chunk-FRJB3NTE.js} +10 -5
  53. package/dist/{chunk-TXFOQZUQ.js → chunk-FSHW3GQU.js} +14 -7
  54. package/dist/{chunk-VIRFG3WG.js → chunk-FTFAPKCW.js} +23 -7
  55. package/dist/{chunk-LL6ED5IB.js → chunk-FTS42N37.js} +2 -2
  56. package/dist/{chunk-HCNIB3EC.js → chunk-FYPTWYCU.js} +4 -4
  57. package/dist/{chunk-MIS6F4HM.js → chunk-G2XSDIYS.js} +4 -4
  58. package/dist/{chunk-ZY55DO5P.js → chunk-G6BEJ3NA.js} +2 -2
  59. package/dist/{chunk-RYWNNJK5.js → chunk-GA6HTO3O.js} +2 -2
  60. package/dist/{chunk-ZYECXDVV.js → chunk-GBPIFCWL.js} +5 -5
  61. package/dist/{chunk-JIKGT7DO.js → chunk-GE3JV5SI.js} +1 -1
  62. package/dist/{chunk-GCINMMFL.js → chunk-GJZMKMWO.js} +2 -2
  63. package/dist/{chunk-6X73VFCX.js → chunk-GT7PZCTK.js} +2 -2
  64. package/dist/{chunk-TT6LN55R.js → chunk-GUC73LRA.js} +8 -8
  65. package/dist/{chunk-ZC6H2ERE.js → chunk-GYM22X2X.js} +5 -5
  66. package/dist/{chunk-V7WCTXEH.js → chunk-H3R4PAOI.js} +5 -5
  67. package/dist/{chunk-QW7NGUYW.js → chunk-H5OM5G3O.js} +244 -173
  68. package/dist/{chunk-WXKSB2N3.js → chunk-HM5X73PY.js} +3 -3
  69. package/dist/{chunk-K6SWZ6H4.js → chunk-HMV2VGTU.js} +54 -54
  70. package/dist/{chunk-G4WRZU5T.js → chunk-HXFUCPZO.js} +7 -7
  71. package/dist/{chunk-ECQXASG3.js → chunk-IFHFJR5O.js} +2 -2
  72. package/dist/{chunk-7AKH4QDJ.js → chunk-J2KY2VNC.js} +96 -65
  73. package/dist/{chunk-74OPNM2Z.js → chunk-JHAZK4RY.js} +3 -3
  74. package/dist/{chunk-JAYHFXWH.js → chunk-LWGCUB2A.js} +7 -7
  75. package/dist/{chunk-CJGLAQRD.js → chunk-LXJ72GY2.js} +4 -4
  76. package/dist/{chunk-OZWAITII.js → chunk-M2IB6N4V.js} +6 -6
  77. package/dist/{chunk-GKQTXUOW.js → chunk-MOVRSULZ.js} +2 -2
  78. package/dist/{chunk-QAEBBTYR.js → chunk-MSYMEP7Y.js} +7 -7
  79. package/dist/{chunk-Y453TW6J.js → chunk-NCERS5QH.js} +2 -2
  80. package/dist/{chunk-T3HNISBN.js → chunk-NDRIMFSH.js} +3 -3
  81. package/dist/{chunk-HXFLHA5K.js → chunk-NH5Z2NOD.js} +2 -2
  82. package/dist/{chunk-FXZEZAV2.js → chunk-NLWYNVJV.js} +3 -3
  83. package/dist/{chunk-66ZU2CD5.js → chunk-O2BLNQEC.js} +236 -17
  84. package/dist/{chunk-5SKWGCAJ.js → chunk-O7Z3LF44.js} +5 -5
  85. package/dist/{chunk-DBDTQR23.js → chunk-OTQF4B37.js} +4 -4
  86. package/dist/{chunk-SL55XKVL.js → chunk-PCY4IPXK.js} +25 -25
  87. package/dist/{chunk-ZDVVIJPU.js → chunk-PODT53SQ.js} +4 -4
  88. package/dist/{chunk-GBSHHNSD.js → chunk-PRSNMSVG.js} +3 -3
  89. package/dist/{chunk-UNFQN3TT.js → chunk-Q3CBDXKL.js} +3 -3
  90. package/dist/{chunk-P7GKTV7N.js → chunk-Q4LJCCH5.js} +75 -32
  91. package/dist/{chunk-DGYXCIBV.js → chunk-Q6AKSLD2.js} +2 -2
  92. package/dist/{chunk-7FIMUFBP.js → chunk-QDPY7RN3.js} +3 -3
  93. package/dist/{chunk-MGG4CHO4.js → chunk-QIT2GGNB.js} +3 -3
  94. package/dist/{chunk-VXHXSGPU.js → chunk-QTOW6YXL.js} +8 -8
  95. package/dist/{chunk-5SJQAJLF.js → chunk-QYZSNN35.js} +3 -3
  96. package/dist/{chunk-NNI5R6V6.js → chunk-R7Y6S7FF.js} +72 -72
  97. package/dist/{chunk-BEKEOXNG.js → chunk-RGPHFHJU.js} +2 -2
  98. package/dist/{chunk-YCKKL5PD.js → chunk-RH3NQTGQ.js} +53 -47
  99. package/dist/{chunk-5FJ4M4HB.js → chunk-RHH6SCB4.js} +17 -32
  100. package/dist/{chunk-M7O3T7IM.js → chunk-RIT3WBBX.js} +4 -4
  101. package/dist/{chunk-45K2QZBR.js → chunk-RKNCISPM.js} +3 -3
  102. package/dist/{chunk-NPYYDTXS.js → chunk-RKTVXFBV.js} +5 -5
  103. package/dist/{chunk-AXNX4NWN.js → chunk-RLQX6LHW.js} +37 -37
  104. package/dist/{chunk-FIERONKM.js → chunk-ROWYW3JF.js} +2 -2
  105. package/dist/{chunk-LSJ3SQEU.js → chunk-RVWWNNZQ.js} +4 -4
  106. package/dist/{chunk-4MIV244X.js → chunk-SGEOXJIH.js} +9 -2
  107. package/dist/{chunk-QRMKQYCB.js → chunk-SINL5WMI.js} +2 -2
  108. package/dist/{chunk-Z6N5N4MN.js → chunk-SIW2HT2H.js} +21 -5
  109. package/dist/{chunk-IEDQT4Z3.js → chunk-SOAZIMWL.js} +12 -12
  110. package/dist/{chunk-R3GPRNBT.js → chunk-SVQMDVND.js} +87 -16
  111. package/dist/{chunk-45ZUMF4E.js → chunk-TPUAXIPR.js} +2 -2
  112. package/dist/{chunk-76SBT7KS.js → chunk-U56HK2RG.js} +7 -5
  113. package/dist/{chunk-RXNMZM6H.js → chunk-UDW2KAVF.js} +6 -6
  114. package/dist/{chunk-NDV6CBR7.js → chunk-UH5VQGNR.js} +2 -2
  115. package/dist/{chunk-75QC66XI.js → chunk-V2MIBJZU.js} +2 -2
  116. package/dist/{chunk-N72XNQNJ.js → chunk-V4466NNS.js} +14 -14
  117. package/dist/{chunk-XPSDDTUZ.js → chunk-VCFRALU7.js} +3 -3
  118. package/dist/{chunk-5KJBWIDZ.js → chunk-VQDVEHDB.js} +2 -2
  119. package/dist/{chunk-6EFXPTHT.js → chunk-WAP5362D.js} +5 -5
  120. package/dist/{chunk-DH6O5NQU.js → chunk-WDN4QIJ4.js} +29 -20
  121. package/dist/{chunk-XLP4CNSF.js → chunk-WGGATSIP.js} +6 -6
  122. package/dist/{chunk-XY4OBD26.js → chunk-WGKKDGSA.js} +4 -4
  123. package/dist/{chunk-ZPJXWMHK.js → chunk-WLZSKD7E.js} +4 -4
  124. package/dist/{chunk-7REDHC4N.js → chunk-X5NF3ZXW.js} +69 -14
  125. package/dist/{chunk-5W7S2SCA.js → chunk-XAE4NIZ2.js} +4 -4
  126. package/dist/{chunk-SPLRKCFV.js → chunk-XDGLYIB2.js} +2 -2
  127. package/dist/{chunk-WS2X5BB2.js → chunk-YYBBJPCL.js} +5 -5
  128. package/dist/{chunk-ZOHEHIFS.js → chunk-YYDM4DNP.js} +2 -2
  129. package/dist/{chunk-SH4RY6QX.js → chunk-Z73I7Q2H.js} +1536 -413
  130. package/dist/{chunk-GRXX2TOJ.js → chunk-ZHFSIQ6E.js} +2 -2
  131. package/dist/{chunk-SXMZNSQ6.js → chunk-ZQUBCGGR.js} +8 -8
  132. package/dist/{chunk-ZRXDPCMN.js → chunk-ZYZ7GRX3.js} +2 -2
  133. package/dist/cli.d.ts +3 -3
  134. package/dist/cli.js +62 -61
  135. package/dist/codegen-command-HCHTNHDF.js +183 -0
  136. package/dist/codegen.d.ts +3 -3
  137. package/dist/codegen.js +5 -5
  138. package/dist/{commands-5ILSWDSV.js → commands-Z2QZOORB.js} +3 -3
  139. package/dist/{completion-UNKBVVDT.js → completion-LFXXNQGR.js} +3 -3
  140. package/dist/{config-NTOASFCA.js → config-7GGINOFY.js} +4 -4
  141. package/dist/{deploy-command-BYAZZF37.js → deploy-command-LYZ76OBA.js} +69 -68
  142. package/dist/{deploy-source-QCPZWNJO.js → deploy-source-AJESF6J2.js} +32 -32
  143. package/dist/{dev-env-sync-6MHK3UHC.js → dev-env-sync-PZEIRCFC.js} +63 -62
  144. package/dist/{diagnostics-FNVNRYMB.js → diagnostics-T3RN3372.js} +2 -2
  145. package/dist/{display-name-hint-MYXCCAOP.js → display-name-hint-5GLJGPQ6.js} +11 -11
  146. package/dist/{emit-YLt3GfsZ.d.ts → emit-DlOKIJER.d.ts} +185 -96
  147. package/dist/env-example-refresh-HLE2HRV4.js +136 -0
  148. package/dist/{env-pull-command-KUIEKBTM.js → env-pull-command-OTTZHTLK.js} +52 -52
  149. package/dist/{env-target-Y77RLRS5.js → env-target-VXOMKCMO.js} +14 -14
  150. package/dist/{env-var-command-BZWJD75C.js → env-var-command-TDVSO3JY.js} +41 -41
  151. package/dist/{ephemeral-VLPRDNEJ.js → ephemeral-2DXWP3VK.js} +9 -9
  152. package/dist/{ephemeral-command-SYKDPALW.js → ephemeral-command-AX5TRR23.js} +52 -52
  153. package/dist/{ephemeral-state-RUOU2GFS.js → ephemeral-state-56XEDUJW.js} +12 -12
  154. package/dist/{generate-command-CSQDQZSW.js → generate-command-LMSKMR4J.js} +89 -88
  155. package/dist/{gitignore-OQGYM7DO.js → gitignore-GKM5G2DJ.js} +15 -15
  156. package/dist/{guards-JUYBDLZY.js → guards-LQ7PSXOL.js} +51 -15
  157. package/dist/{impersonate-command-HSFCZBV6.js → impersonate-command-QTEOBL5N.js} +37 -37
  158. package/dist/{import-T4ZTOTBT.js → import-VJQGIS33.js} +5 -5
  159. package/dist/index.d.ts +597 -118
  160. package/dist/index.js +29 -28
  161. package/dist/init-command-OMZVE54Z.js +143 -0
  162. package/dist/{init-modules-BL2SR5RK.js → init-modules-OTISW6LL.js} +8 -8
  163. package/dist/{init-web-DYE2FEXL.js → init-web-25QJ4JWB.js} +3 -3
  164. package/dist/internal.d.ts +55 -8
  165. package/dist/internal.js +696 -506
  166. package/dist/{io-PGTCBSIQ.js → io-47TFRYDB.js} +6 -6
  167. package/dist/{keep-data-merge-SHF75FC7.js → keep-data-merge-ECLY5DYP.js} +38 -38
  168. package/dist/{lambda-config-reconcile-VOBVZPWS.js → lambda-config-reconcile-CC5QIP6E.js} +3 -3
  169. package/dist/{landed-F7PCHGCK.js → landed-VIUFHLCJ.js} +5 -5
  170. package/dist/{landing-record-7EOLEKH3.js → landing-record-RVE5WLFS.js} +22 -22
  171. package/dist/{live-diff-M2OLXKM6.js → live-diff-KJ2TWWWT.js} +14 -14
  172. package/dist/{local-engine-choice-TOC3UYZZ.js → local-engine-choice-CMG5V7RL.js} +35 -35
  173. package/dist/{local-engine-command-6KSRDZBR.js → local-engine-command-UMY37AZL.js} +40 -40
  174. package/dist/{local-engine-deploy-4N4NFZ4T.js → local-engine-deploy-XAEDT55W.js} +12 -12
  175. package/dist/{local-engine-lookup-AQTUGSBT.js → local-engine-lookup-WBYTY2JE.js} +2 -2
  176. package/dist/{local-engine-mcp-bridge-AMYRH4SY.js → local-engine-mcp-bridge-3H5OXBWQ.js} +5 -5
  177. package/dist/{local-engine-mcp-command-XTP3EATV.js → local-engine-mcp-command-AV2T3U4B.js} +42 -42
  178. package/dist/{local-engine-process-OD5OSWDG.js → local-engine-process-35B2KQED.js} +7 -7
  179. package/dist/{local-engine-update-check-G3YCBXRE.js → local-engine-update-check-VXJZSIJU.js} +5 -5
  180. package/dist/{lock-HDCHD2ON.js → lock-JBKTDEDO.js} +4 -4
  181. package/dist/{lock-commands-437P6BHY.js → lock-commands-PSKHBOKS.js} +67 -66
  182. package/dist/{login-command-BNRDAVFV.js → login-command-M7RKU3DR.js} +27 -27
  183. package/dist/{logout-command-FCGCHB7Y.js → logout-command-DAC3XKLT.js} +17 -17
  184. package/dist/{loop-WOAEXMTC.js → loop-HILLODVH.js} +15 -15
  185. package/dist/{marketplace-command-SUBJZPJV.js → marketplace-command-2M33OTSN.js} +30 -30
  186. package/dist/{marketplace-resolve-JR4BBJ6K.js → marketplace-resolve-63QWMQZU.js} +6 -6
  187. package/dist/{meta-client-AYJS3RQ3.js → meta-client-FC4DWPAC.js} +15 -15
  188. package/dist/{module-manifest-63I5GRK4.js → module-manifest-NWJWAQLQ.js} +4 -4
  189. package/dist/node.d.ts +8 -8
  190. package/dist/node.js +71 -70
  191. package/dist/{operation-outcome-ORQPVJKB.js → operation-outcome-3V4G7QD3.js} +24 -24
  192. package/dist/{output-target-KNHHNDM3.js → output-target-LTU4L3IA.js} +16 -16
  193. package/dist/{plan-disclosure-4DUFRGCP.js → plan-disclosure-6MG4YYJV.js} +28 -28
  194. package/dist/{plugin-contributions-YYEP7IWH.js → plugin-contributions-DD6R6RL6.js} +5 -5
  195. package/dist/{plugin-prompt-GKCQKNYI.js → plugin-prompt-UX2TT5NS.js} +5 -5
  196. package/dist/{plugin-questions-P7MA3TYI.js → plugin-questions-WE2F4ZC4.js} +4 -4
  197. package/dist/{preflight-command-32GFVKSN.js → preflight-command-724B7Y73.js} +75 -74
  198. package/dist/{profile-command-U2XTKOMF.js → profile-command-REIJ4F3Y.js} +28 -28
  199. package/dist/{profile-pointer-JJ7K5O2R.js → profile-pointer-RCPHVTJV.js} +4 -4
  200. package/dist/{project-dependency-X3KCWBK5.js → project-dependency-TPVV3YIX.js} +7 -7
  201. package/dist/{project-sdk-YHJZRCNB.js → project-sdk-DKZBK5H5.js} +4 -4
  202. package/dist/promote-command-5FK2NFHG.js +149 -0
  203. package/dist/{prompt-QNMJIWNI.js → prompt-OYQHQWKI.js} +4 -4
  204. package/dist/{publish-command-5ZVZ6IYT.js → publish-command-VEDUWLVB.js} +72 -71
  205. package/dist/pull-command-UXNEJSDI.js +171 -0
  206. package/dist/{pull-superseded-6HADGGC5.js → pull-superseded-3SSM3JFT.js} +4 -4
  207. package/dist/{raw-where-gWGr-E4t.d.ts → raw-where-CinW0keO.d.ts} +32 -4
  208. package/dist/release-command-BCKJ4BUN.js +153 -0
  209. package/dist/{release-ns-command-LDN5DOKQ.js → release-ns-command-VFI4PPSX.js} +96 -95
  210. package/dist/{retry-command-LFZYEVRU.js → retry-command-WP4ZI6CJ.js} +8 -8
  211. package/dist/{routes-manifest-BMAOL6WN.js → routes-manifest-N73THJB3.js} +16 -16
  212. package/dist/routes-manifest-file-R3JLJ5CA.js +41 -0
  213. package/dist/scaffold.js +2 -2
  214. package/dist/{secrets-file-7QM3ORGX.js → secrets-file-GF46TDY7.js} +15 -15
  215. package/dist/{secrets-fill-command-OZ537VOD.js → secrets-fill-command-HKNROT6W.js} +66 -65
  216. package/dist/{seed-ATGBOEJP.js → seed-W5FNE6IB.js} +13 -13
  217. package/dist/{source-resolve-QYSWA3QR.js → source-resolve-QYSVNJMY.js} +22 -22
  218. package/dist/{static-host-MO4VDHL7.js → static-host-3HPZKVKK.js} +5 -5
  219. package/dist/{status-command-IEB4K7ME.js → status-command-RLXDDCZA.js} +38 -38
  220. package/dist/{store-AJX4MC7Y.js → store-B63BQV6R.js} +6 -6
  221. package/dist/{store-DspGMsFY.d.ts → store-Dg9FLJkx.d.ts} +185 -11
  222. package/dist/sync-baseline-GRS33AB5.js +38 -0
  223. package/dist/{sync-contributions-DLV5JZUK.js → sync-contributions-BV7DFWBZ.js} +9 -9
  224. package/dist/{sync-record-NE62ERA3.js → sync-record-AWFCSS4D.js} +15 -15
  225. package/dist/{table-TFD4ZQXA.js → table-WJ7YDJ6Q.js} +12 -12
  226. package/dist/{tables-command-IMCVPUFY.js → tables-command-EXHXLLN6.js} +41 -41
  227. package/dist/{tenant-IIYECNWO.js → tenant-IXIW3FOI.js} +10 -10
  228. package/dist/{tenant-command-77KG76MU.js → tenant-command-D5H7MR3C.js} +104 -103
  229. package/dist/{test-command-NSPU4RUO.js → test-command-ORMWZXC3.js} +56 -45
  230. package/dist/{tests-JWQRHFCT.js → tests-N4MMBABH.js} +6 -6
  231. package/dist/{token-BDHD7GU3.js → token-EFSD6WSQ.js} +13 -13
  232. package/dist/{toolchain-hooks-QHJRDCRW.js → toolchain-hooks-IJWV3ZQS.js} +18 -18
  233. package/dist/{toolchain-modules-LY7BMYG6.js → toolchain-modules-BC37MYYD.js} +5 -5
  234. package/dist/{toolchain-peers-FQJBTKEB.js → toolchain-peers-EMOYN4U7.js} +8 -8
  235. package/dist/{tracked-backend-BIR7YJCE.js → tracked-backend-IPEGNGNI.js} +34 -34
  236. package/dist/update-check-4YTFF7NB.js +141 -0
  237. package/dist/{upgrade-command-YCADQCIA.js → upgrade-command-J4CPYEGO.js} +68 -67
  238. package/dist/{whoami-command-IZCTUPM4.js → whoami-command-XGVTKQSL.js} +16 -16
  239. package/dist/{workspace-TK52V7WO.js → workspace-JGUNVFRE.js} +5 -5
  240. package/dist/{workspace-binding-3UT6PP4B.js → workspace-binding-MQ2QIWOJ.js} +15 -15
  241. package/dist/{workspace-command-46OCB6XT.js → workspace-command-LSEG62RA.js} +100 -99
  242. package/dist/{workspace-env-PVPOWFNZ.js → workspace-env-7U7OLRUO.js} +18 -12
  243. package/dist/{workspace-export-PUEXKZNS.js → workspace-export-3KMWNZDD.js} +5 -5
  244. package/dist/{writable-LMMG4AFZ.js → writable-X7BCN7XE.js} +4 -4
  245. package/dist/xano-RLSNDM7O.js +44 -0
  246. package/dist/{xanosdk-import-XXJT365U.js → xanosdk-import-Y5SBF4LP.js} +10 -10
  247. package/dist/{xanosdk-project-CJKRLQ6U.js → xanosdk-project-5XARMFZ7.js} +13 -13
  248. package/dist/{xdo-D4OwfF2J.d.ts → xdo-DNGZGO1j.d.ts} +50 -12
  249. package/guides/authoring.md +1 -0
  250. package/guides/codes.md +33 -3
  251. package/guides/coverage.md +2 -2
  252. package/guides/object-kinds.md +1 -1
  253. package/guides/typed-frontend.md +9 -0
  254. package/llms/client.md +54 -36
  255. package/llms/errors.md +26 -6
  256. package/llms/fields.md +56 -32
  257. package/llms/filters.md +55 -46
  258. package/llms/kinds-agent-mcp.md +10 -9
  259. package/llms/kinds-core.md +19 -15
  260. package/llms/kinds-knowledge.md +4 -4
  261. package/llms/kinds-realtime.md +25 -23
  262. package/llms/lambda.md +42 -30
  263. package/llms/legacy.md +6 -7
  264. package/llms/lock.md +21 -17
  265. package/llms/object-kinds.md +9 -11
  266. package/llms/statements-calls.md +41 -20
  267. package/llms/statements-catalog.md +32 -25
  268. package/llms/statements-data.md +35 -25
  269. package/llms/statements-runtime.md +28 -18
  270. package/llms/tests.md +20 -7
  271. package/llms/toolchain.md +12 -9
  272. package/llms/triggers.md +15 -19
  273. package/llms/values.md +16 -9
  274. package/llms-full.txt +647 -506
  275. package/llms.txt +120 -137
  276. package/manifest.json +147 -95
  277. package/package.json +1 -1
  278. package/skills/xano-backend/SKILL.md +10 -12
  279. package/types/lambda-globals.d.ts +6 -1
  280. package/dist/branch-commands-4PJEBNRK.js +0 -80
  281. package/dist/codegen-command-RDD4GL35.js +0 -182
  282. package/dist/env-example-refresh-MQWHY7ZS.js +0 -135
  283. package/dist/init-command-6Z7QNVDY.js +0 -142
  284. package/dist/promote-command-OO56IZBT.js +0 -148
  285. package/dist/pull-command-LT5PCEIW.js +0 -170
  286. package/dist/release-command-RBUOXIH7.js +0 -152
  287. package/dist/routes-manifest-file-MPOVKD6N.js +0 -41
  288. package/dist/sync-baseline-IB7MABZO.js +0 -38
  289. package/dist/update-check-JDARCXAX.js +0 -140
  290. package/dist/xano-EOUVXNQX.js +0 -43
package/llms/errors.md CHANGED
@@ -11,34 +11,54 @@
11
11
  - `Value is less than the minimum value of 1` (HTTP 400) — a `db.get` given `0` in an editor-authored workspace (SDK field-match `db.get` answers 200 + null). `llms/statements-data.md`.
12
12
  - `Invalid op: <op>` — a `cmp` operator (`in`, `like`, …) in a RUNTIME condition, which takes the `expr` set only; write `or(expr(...), expr(...))`. `llms/kinds-core.md`.
13
13
  - `Unsupported param format` / `Unsupported parameter reference` — an aggregate or `eval` `name` that is not a bare column, or a bare `eval` name for a joined column. `llms/statements-data.md`.
14
- - `ParseError: Invalid value for param` (HTTP 400) — `contains`/`@>`/`overlaps` on a text column (use `includes`), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.
14
+ - `ParseError: Invalid value for param` (HTTP 400) — `contains`/`@>`/`overlaps` on a text column (use `includes`, for scalar text only: a list column 500s), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.
15
15
  - `ERROR_FATAL: <Type> does not exist: <type>:<n>` — `s.api.call`/`s.task.call`/`s.trigger.call`/`s.workflow_test.call` outside a workflow test; share logic via `defineFunction` + `s.function.run`. `llms.txt`.
16
16
  - `ERROR_FATAL "Unable to decode."` — a populated JSON string where the engine expects `c.obj`'s form; write `c.obj({...})` or `obj({...})`. `llms/values.md`.
17
+ - `ERROR_FATAL "Invalid zip"` on `s.zip.view_contents`/`extract` of an uploaded `input.file` — the CLIENT-supplied Content-Type was not `application/zip` (the bytes are not checked; curl's `-F` default is `application/octet-stream`). Send `new File([…], "x.zip", { type: "application/zip" })`. A wrong password (`Extraction failed (wrong password?)`) and a non-zip both 500 — wrap the call in `s.try_catch`. `llms/statements-runtime.md`.
18
+ - `ERROR_FATAL "Infinite recursion detected. Please fix."` — `s.function.run`/`.call` nested past ~25 deep in one request (the engine's variable-stack limit), even for correct bounded recursion. Recurse iteratively (`s.while` over an explicit list) or batch. `llms/statements-calls.md`.
17
19
  - `Precondition failed.` in place of your message — `error` was a bare string; pass `c.text("…")`. `llms/fields.md`.
18
20
  - `Param: token - Text filter requires an integer, float, string or boolean value` — `s.api.call` `auth.token` given a tagged `Value`; it must be a bare string. `llms/statements-calls.md`.
19
21
  - Every `s.db.add` into one table 400s naming a column while complaining about its VALUE — the column is named `run`. `llms.txt`.
20
- - HTTP 200 with an EMPTY body where `0` was expected — a bare `returnType: "count"` of zero; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.
22
+ - HTTP 200 with an EMPTY body where `0` was expected — a bare `returnType: "count"` of zero can answer either; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.
21
23
  - HTTP 200 with `[]` from a `db.query` that matches rows — a paged query (`metadata: true`, the default) whose `output` names bare columns; the selection applies to the ENVELOPE, so prefix them (`items.<column>`) or set `metadata: false` inside `paging`. `llms.txt`; `llms/statements-data.md`.
22
24
  - Every field mapped off an `s.api.request` result reads `null` — the upstream answered an error (a 403 for a missing `User-Agent` is the common one) and its body arrived as ordinary `response.result`; send a `User-Agent` and gate on `response.status`. `llms/statements-calls.md`.
23
25
  - A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) — the body threw; use the preloaded globals, the surface's bindings, and `capture`. `llms/lambda.md`.
24
26
  - `Unable to locate request.` (404) on an endpoint that deployed — a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.
25
27
  - A browser call fails on a missing `access-control-allow-origin` while deploy looks fine — CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.
26
- - 403 `Forbidden: Origin not allowed` from an MCP server URL — the request came from a browser; MCP endpoints refuse every `Origin`, so call them server-side. `llms/kinds-agent-mcp.md`.
27
- - `ERROR_FATAL` `The free model is not available in this process.` — an `xano-free` agent run on the Xano Engine on this machine; it runs only on Xano's cloud. `llms/kinds-agent-mcp.md`.
28
+ - `ERROR_FATAL` `The free model is not available in this process.` — an `xano-free` agent run on a Xano Engine; it runs only on Xano's cloud. `llms/kinds-agent-mcp.md`.
29
+ - `Not supported. Please upgrade your Xano instance.` (HTTP 403) — a capability the instance lacks; on the Xano Engine on this machine, every `s.storage.sign_private_url` answers it. Test it with `deploy --ephemeral`. `llms/fields.md`.
30
+ - An MCP `tools/call` answers `isError: true` with `Unable to get successful response from executing tool` — the tool's run failed without a usable `{code, message}`, and the authored message is dropped. Common cause: a tool reading `auth()` behind an entry naming no auth table (`export()` warns `toolset.tool-reads-auth-ungated`); wrap it `{ tool: <handle>, auth: <auth table> }`. `llms/kinds-agent-mcp.md`.
28
31
  - A websocket is closed right after the handshake — a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.
29
32
  - `to_throw failed - response is ok` around an auth-refused call — `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.
30
33
  - Output reads `Hi [object Object]` — a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.
31
34
 
32
35
  ### Build-time and tooling failures
33
36
 
34
- - `export --strict` fails on a warning whose shape is meant (a fixture pinning a hazard) — accept it on ITS def only with `diagnostics: { allow: ["<code>"] }`, which takes any warning code that def raised (never an error) on every def kind. Accepted warnings are still listed: `export({ accepted: [] })`, `--json` `accepted[]`. An allowed code the def no longer raises warns `diagnostics.allow-unused`.
37
+ - `export --strict` fails on a warning whose shape is meant (a fixture pinning a hazard) — accept it on ITS def only: add `diagnostics: { allow: ["<code>"] }`, which takes any warning code that def raised, on any def kind (warnings only, never an error). Accepted warnings are still listed: `export({ accepted: [] })`, `--json` `accepted[]`. An allowed code the def no longer raises warns `diagnostics.allow-unused`.
35
38
  - `must be ES modules` — package.json says `"type": "commonjs"`; set `"type": "module"`. `llms.txt` Quickstart.
36
39
  - A response types as `StackTupleWidened` — a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.
37
40
  - `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
38
41
  - `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
39
- - A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_WORKSPACE_CHANGED` (deploy over objects edited in Xano since the last sync; `details.objects`; pull first or `--overwrite`), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
40
42
  - A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `npx @xano/sdk login`, which rotates a single-use refresh token.
41
43
 
44
+ ### CLI failure documents
45
+
46
+ A CLI command that fails under `--json` or piped (unless stdout carries data) writes `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }` to stdout, as does a failed release write. Codes:
47
+
48
+ | `code` | `details` |
49
+ |---|---|
50
+ | `SDK_SEED_IN_STATIC` | `details.leaks[]` → `publicSeed` |
51
+ | `SDK_EXPORT_INVALID` | `details.diagnostics[]`, `--strict` too |
52
+ | `SDK_LIVE_BRANCH_MISMATCH` | `details.conflictsWith` |
53
+ | `SDK_CREDENTIAL_REJECTED` | `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh |
54
+ | `SDK_WORKSPACE_CHANGED` | `details.objects`: objects edited in Xano since the last sync. Pull first or deploy `--overwrite`. |
55
+ | `SDK_USAGE` | `details.reason: "needs-confirmation"`: run its `Re-run as` |
56
+ | `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_ERROR` | — |
57
+
58
+ - Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope.
59
+ - `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`).
60
+ - Backend documents add `selector` and `workspaceId`.
61
+
42
62
  ### CLI exit codes
43
63
 
44
64
  A failure document's `exitCode` matches.
package/llms/fields.md CHANGED
@@ -6,19 +6,22 @@ Author table columns + function/API inputs with the typed catalog: `f.<type>(opt
6
6
  for columns, `input.<type>(opts?)` for inputs. Common opts: `required`, `nullable`,
7
7
  `default`, `description`, `access` (a read omits `"internal"` columns, returns `"private"` ones; `InferRow`
8
8
  is the full row, both kept), `sensitive` (masks the input's value in request logs; a read still RETURNS a sensitive column — `access: "internal"` keeps it out).
9
- **`nullable` defaults PER TYPE, matching the engine's own column-creation API**: `true`
10
- for `f.vector`, `f.uuid`, every `f.geo.*` and every file type (`f.image`/`f.video`/
11
- `f.audio`/`f.attachment`), `false` for everything else (text, int, decimal, bool, email,
12
- enum, json, object, password, date, tableRef); inputs add date, timestamp and file, so an
13
- omitted one binds `null` (a `required` one still accepts an explicit `null`). Pass `nullable` to override —
14
- e.g. `f.geo.polygon({ nullable: false })`. An empty default becomes NULL only when
9
+ ⚠ On a column, `required` is not a write-time constraint: `db.add`/`edit` store a null, `""`, or (after a `trim` method) whitespace-only value at HTTP 200 — it only shapes the seed write-shape, the typed row, and the editor. Enforce presence on the input (`input.*({ required: true })` plus a non-empty check — a `min: 1` method or an `s.precondition`).
10
+ ⚠ An `f.date` COLUMN does not validate the written value: an invalid calendar date ROLLS OVER into a different valid one (`"2020-13-45"` stores `"2021-02-14"`) instead of failing, so a value arriving through `input.text`/`input.json` or a computed var is silently corrupted. Validate at the boundary with `input.date` (it rejects the same string with a 400).
11
+ **`nullable` defaults per type**: `true` for `f.vector`, `f.uuid`, every `f.geo.*` and every
12
+ file type (`f.image`/`f.video`/`f.audio`/`f.attachment`); `false` for the rest. Inputs add
13
+ date, timestamp and file, so an omitted one binds `null`
14
+ (a `required` one still accepts an explicit `null`). Pass `nullable` to override.
15
+ ⚠ Except `input.geo.*`: an omitted optional geo input is not bound at all, so `inp("p")` 500s `Unable to locate input: p`. Mark it `required: true`, or read it only inside an `s.conditional` that a sibling flag gates.
16
+ An empty default becomes NULL only when
15
17
  nullable, so a non-null `f.vector(8)` column fails to create (`''` is not a vector).
16
18
  **`f.geo.*` values are `{ type, data }`, not GeoJSON.** The same shape goes in and comes
17
19
  back. `type` per column: `point` → `"point"`, `data` `{ lng, lat }`; `multipoint` → `"points"`,
18
20
  `linestring` → `"path"`, `polygon` → `"poly"` (ring closed for you), `data` `[{ lng, lat }, …]`;
19
21
  `multilinestring` → `"paths"`, `multipolygon` → `"polys"`, `data` `[[{ lng, lat }, …], …]`.
20
22
  Any other spelling (`"multipoint"`, `"linestring"`, `"Point"`) 400s `Only strings are supported for:`.
21
- Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a read never returns one.
23
+ Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a COLUMN read never returns one.
24
+ ⚠ An `input.geo.*` is the exception: `inp("p")` inside the stack reads back as WKT TEXT (`"POINT(10 20)"`), NOT the `{ type, data }` you POSTed — it becomes `{ type, data }` only once WRITTEN to a geo column and read back. So `InferResponse` of a bare `inp()` of a geo input is wrong (it types `{ type, data }`); treat a bound geo input as a `string`.
22
25
  `methods` (validators/transforms, names per type below): `"trim"`, `"min:8"`
23
26
  (a text arg keeps its `:`: `"startsWith:https://"`), or `{ name, arg }` — for unlisted names and `pattern`'s error text.
24
27
  `f.json({children})` declares the nested shape stored INSIDE a json column — an ARRAY of
@@ -26,10 +29,11 @@ Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a read never
26
29
  `f.object` takes positionally. Omit it for an unstructured json column.
27
30
  `f.enum(values)`/`f.vector(size)`/`f.object(children)`/`f.tableRef(table)` take a
28
31
  positional payload before opts — and still accept the standard `FieldOptions` after it
29
- (`f.enum([])`/`input.enum([])` are accepted: a pulled enum with no options, not one to
30
- author — it brands the column `never`, which `InferRow` surfaces as `undefined`.)
31
32
  (e.g. `f.tableRef(users, { required: true })` — only `min`/`max` are listed as tableRef
32
- methods below, but `required`/`nullable`/`description`/… apply like any field.)
33
+ methods below, but `required`/`nullable`/`description`/… apply like any field).
34
+ `f.enum([])`/`input.enum([])` (a pulled enum with no options) brands the column `never`; `InferRow` surfaces it as `undefined`.
35
+ ⚠ An `f.enum` column refuses a non-member (400) but STORES `""`, which an omitted optional
36
+ `input.text`/`input.enum` binds, overriding the `default`; `InferRow` types it members `| ""`. Declare that input `nullable: true` (omitted → `null` → the default).
33
37
  An **OPTIONAL foreign key wants a `0` sentinel, not `nullable: true`**. `f.tableRef` to an int-keyed table stores
34
38
  an `int`, and a null in it is unqueryable: `null` is never a legal `fieldValue`/`id`, so
35
39
  `s.db.get`/`edit`/`del` on that column answer HTTP 400 `Missing param: field_value` rather
@@ -40,10 +44,11 @@ binds `null`, which is the answer the null was reaching for. `export()` warns on
40
44
  An `f.vector(size)` column is SEARCHED through `s.db.query`'s `eval` pipeline, not through
41
45
  any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embedding", op:
42
46
  "vector_cosine_ops" }] }]`, then rank with a distance filter + a sort on its alias (see
43
- `s.db.query` → `eval`). Without that pairing the column stores and indexes but nothing
44
- queries it.
47
+ `s.db.query` → `eval`).
45
48
  `{ array: true }` makes any `f.*` scalar a **list column** — `f.text({ array: true })`
46
- surfaces as `string[]` in `InferRow<typeof table>` (the column analogue of `input.list`).
49
+ surfaces as `string[]` in `InferRow<typeof table>`.
50
+ Filter one to rows containing a value with `contains`/`overlaps` and a LIST operand (NOT a
51
+ scalar — `llms/statements-data.md`).
47
52
  **Seed a table's starting rows with `table({ seed })`.** `seed` takes rows
48
53
  typed against the table's schema as a WRITE shape (a column without
49
54
  `required: true`, and the system columns, may be omitted; `null` needs
@@ -56,8 +61,9 @@ Timestamp seeds: epoch ms, `Date`, ISO 8601 date, or date-time with `Z`/offset;
56
61
  Int seeds: whole, in int64 (past 2^53: a string).
57
62
  ⚠ Prefer `seedFile` for a file: a thunk's `import()` sits in
58
63
  YOUR module, so a bundler emits the JSON as a served chunk. Never put secrets
59
- in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;
60
- declare public ones (demo logins) on the table: `publicSeed: ["password"]`.
64
+ in `seed`. Internal/sensitive/password columns: Seeding them is fine (a seeded user logs in);
65
+ `deploy --static` REFUSES only when a served file of the frontend build contains a seed value
66
+ from one. Declare deliberately shown ones (demo logins) on the table: `publicSeed: ["password"]`.
61
67
  A replacing deploy re-seeds cleanly; `--keep-data` writes no seed rows.
62
68
  `seed` is evaluated on EVERY build, so a computed value (`Date.now()`) is fine:
63
69
  the lock records no seed data.
@@ -68,7 +74,7 @@ Omit `id` and rows auto-number `1..N` (int PK) or take
68
74
  a stable derived uuid (uuid PK); supplying `id` pins it (and
69
75
  resets an int sequence past the max). All-or-nothing — mixing explicit and
70
76
  omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is
71
- `seed`-only — `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.
77
+ `seed`-only — `s.db.bulk.add` DROPS `id` unless `allowIdField: true`. ⚠ After a deploy, the FIRST insert into an UNSEEDED int-keyed table gets `id: 2`, not 1 (a seeded table continues correctly from its max) — so a test or fixture must not assume the first inserted row is `id: 1`.
72
78
  **`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,
73
79
  default `false`): `true` stores fields as JSON in the `xdo` column (+ `gin(xdo)` index),
74
80
  `false` real columns.
@@ -77,10 +83,10 @@ A **column `default` must stay within the BMP** — a 4-byte character (codepoin
77
83
  e.g. an emoji) is rejected at export; put such a value on an `input.<type>({ default })`.
78
84
  `input.*` mirrors `f.*` — every column type below is
79
85
  a legal input (scalars, files `input.image/video/audio/attachment`, `input.geo.*`,
80
- `input.vector(size)`, `input.tableRef(table)`, `input.object(children)`), plus
81
- `input.dbLink(table)` is the odd one: ONE entry that EXPANDS into one input per
82
- COLUMN of the linked table, so read them by column name (`inp("email")`), never by
83
- the entry's own name. `hidden: ["created_at"]` drops columns from that expansion.
86
+ `input.vector(size)`, `input.tableRef(table)`, `input.object(children)`).
87
+ Input-only: `input.dbLink(table)` expands into one input per column of the linked table;
88
+ read them by column name (`inp("email")`), not by the entry's own name.
89
+ `hidden: ["created_at"]` drops columns from that expansion.
84
90
  `input.list(element)` for arrays — wrap any element constructor, e.g.
85
91
  `input.list(input.text())` or `input.list(input.object({ id: f.int() }))`.
86
92
  **A file reaches a column in two steps.** `input.file` is the RAW upload (the request's
@@ -92,6 +98,7 @@ multipart/base64 bytes) and cannot be written to a file column directly: store i
92
98
  `"public"` (a guessable URL): pass `"private"` and hand out `s.storage.sign_private_url`
93
99
  results for anything user-scoped. `create_video`/`create_audio`/`create_attachment` are
94
100
  the same shape for the other file columns, each fed `input.file` (`input.image`/… 400s an upload).
101
+ ⚠ A WRONG-KIND upload to `create_image`/`create_audio`/`create_video` (text sent as an image, or a `.txt` renamed `.png`) fails the request with HTTP 500 `ERROR_FATAL` (`Invalid file extension.` / `This resource is not a valid image.`), not a 4xx. Guard it: wrap the store in `s.try_catch`, or precondition the upload's extension/mime first.
95
102
  **An empty file column is a stored null that `where` does not see as null.** `expr(col("file"), "!=", c.null())`
96
103
  matches EVERY row, and `= c.null()` matches none. Compare a key inside the file instead:
97
104
  `expr(col("file.path"), "!=", c.null())` keeps only the rows holding a file.
@@ -101,6 +108,9 @@ malformed address with a 400 (and trims; add `methods: ["lower"]` to downcase)
101
108
  `regex_matches` needed; `input.int`/`input.decimal`/`input.uuid`/`input.enum([...])`/`input.date`
102
109
  likewise reject or coerce bad input at the boundary. Drop to `input.text` + `s.precondition`
103
110
  only for rules no type expresses.
111
+ ⚠ `input.int` COERCES by TRUNCATION, not refusal: a fractional number binds its integer part
112
+ at HTTP 200 (`1.7` → `1`, `2.9` → `2`), where `"abc"` gets a 400. When a fraction must be
113
+ refused rather than silently floored, take `input.decimal` and check it with `s.precondition`.
104
114
  ⚠ `input.url` is NOT one of them — there is no engine `url` type, so it stores as `text`
105
115
  and validates NOTHING: a `javascript:`/`data:` URL type-checks, imports, and binds. When the value gets navigated
106
116
  to, check the scheme in the stack. It is INPUT ONLY — there is no `f.url` column.
@@ -109,25 +119,39 @@ SECONDS (`date +%s`) bind in January 1970 with no error. An ISO-8601 string keep
109
119
  offset but DROPS fractional seconds (`"…T19:30:00.123Z"` binds `…:00.000`). Send epoch ms
110
120
  (`Date.now()`, `getTime()`) whenever sub-second precision matters.
111
121
  ⚠ `input.list` does NOT reject a non-array: one value binds as a ONE-item list (`"a"` →
112
- `["a"]`), and a non-JSON string given to an `input.object` binds an object of its
113
- children's DEFAULTS — so `input.list(input.object({...}))` given `"notalist"` binds
114
- `[{ name: "", … }]` with a 200. A list `min` does not catch it (that is one item). A string
115
- starting with `[` is parsed as JSON with NO element check at all. When the shape must hold,
116
- mark an object child `required: true` (the default-filled object then 400s with its param
117
- path) and check anything else with `s.precondition`.
118
- ⚠ `s.precondition`'s `error` must be a TAGGED value — `c.text("…")`, not a bare string.
119
- The engine falls back to the generic "Precondition failed." whenever it reads an empty or
120
- non-scalar message, and a bare string lands there, so the client never sees your text. The
121
- `error_type` → HTTP status mapping is correct either way; only the message is lost.
122
+ `["a"]`); a non-JSON string given to an `input.object` binds an object of its
123
+ children's DEFAULTS, so `input.list(input.object({...}))` given `"notalist"` binds
124
+ `[{ name: "", … }]` with a 200 (a list `min` passes: one item). A string starting with `[`
125
+ is parsed as JSON with NO element check. To enforce the shape, mark an object child
126
+ `required: true` (the default-filled object then 400s with its param path); check the rest
127
+ with `s.precondition`.
128
+ ⚠ `s.precondition`'s `error` must be a TAGGED value — `c.text("…")`, not a bare string (warns `stack.precondition-bare-error`).
129
+ A bare string is replaced by the generic "Precondition failed."; the status from `error_type` still applies.
122
130
  `error_type` is how a stack sets a FAILURE status: `badrequest`/`inputerror` → 400, `unauthorized` → 401, `accessdenied` → 403, `notfound` → 404, `toomanyrequests` → 429, `standard` → 500.
131
+ A failed request answers a JSON envelope `{ code, message, payload }`: `code` is the
132
+ `ERROR_CODE_*` string for the `error_type` (`badrequest` → `ERROR_CODE_BAD_REQUEST`,
133
+ `accessdenied` → `ERROR_CODE_ACCESS_DENIED`, `notfound` → `ERROR_CODE_NOT_FOUND`, …;
134
+ `standard`/an uncaught engine error → `ERROR_FATAL`). `message` is the `error` text.
135
+ `payload` is `s.precondition`'s optional structured detail (`obj({...})`), client-visible;
136
+ it is `""` when a precondition sets none and the key is ABSENT entirely on engine errors.
137
+ ⚠ A `db.edit`/`db.del` NotFound carries an EMPTY `message` (just `{code:"ERROR_CODE_NOT_FOUND"}`),
138
+ so a `catch` that re-raises `fl.concat(caught("message"))` yields only its prefix and an
139
+ `expect.to_throw(c.text(...))` can never match it — re-raise with your own `error` text.
140
+ ⚠ An uncaught `s.throw` (including one inside a function run with `s.function.run`):
141
+ - answers HTTP **200** with `{ payload, statement: "Throw Error" }`, so `res.ok` is true — UNLESS it
142
+ sets `status`: `s.throw({ name: "NOT_ALLOWED", value: c.text("no access"), status: 403 })`
143
+ answers 403 with that body (`status` is a whole number, 100–599).
144
+ - The status applies only when nothing catches the throw; a caught throw leaves the response status alone.
145
+ - The body carries `value` as `payload` and never the `name`.
146
+ - For the `{ code, message, payload }` envelope, fail with `s.precondition` or `guard.require` instead.
147
+
123
148
  For any other status — and for a redirect — use `respond.*`, which is sugar over
124
149
  `s.util.set_header` (that statement reaches the status line): `respond.status(201)`,
125
150
  `respond.redirect(url, { status?: 301|302|303|307 })` (a TUPLE — spread it; a `Location`
126
151
  alone does NOT redirect), and `respond.header(name, value)`. Position in the stack does not
127
152
  matter, a later status wins, and a FAILING `precondition` still wins over anything set
128
153
  before it. ⚠ `204` answers with an empty body whatever `response` says. ⚠ `respond.status`
129
- REFUSES `308`/`425`/`451`/`102`/`103`: the platform writes those and does not act on them,
130
- so the response is 200 with nothing reported — use 301, 429 and 403 instead.
154
+ REFUSES `308`/`425`/`451`/`102`/`103` (they would answer 200, nothing reported); use 301, 429 and 403 instead.
131
155
  Normalizing transforms run on bind too — put `trim`/`lower`/`upper` on the input's `methods`
132
156
  so `inp("name")` reads already-normalized; don't reroll `var $x = inp("name")|trim` in the stack.
133
157
  ⚠ `f.decimal`'s size depends on the table's layout; it takes no precision or scale option.
package/llms/filters.md CHANGED
@@ -4,38 +4,45 @@
4
4
 
5
5
  Attach to a value with `withFilters(v, fl.name(...))` — the value `filters[]`
6
6
  pipeline. Filters are passed spread (canonical); the array form
7
- `withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed:
8
- the ones below carry named args, and the rest take NO arguments — call them
9
- `fl.<name>()`, and passing an argument is a compile error.
10
- A typed filter's declared argument list is an EXACT count, not a floor: passing more
11
- than it lists THROWS, in the type and at runtime. The extra argument used to ride into
12
- the filter's arg list, where the engine either ignores it or fails opaquely on a live
13
- endpoint. `filter("name", …)` is the untyped escape for a filter the catalog
14
- under-declares. Seven declared filters are exceptions the engine really does take more from, so they
15
- stay variadic: `concat` (trailing separator), `index_by` (trailing list flag), `get` (trailing variable
16
- map), `array_merge` and `array_merge_recursive` (any number of arrays), `jwe_encode` and
17
- `jwe_decode`. To send more than a zero-argument filter's `()` accepts, use the same
18
- `filter("name", …)` escape. A filter with NO declared list takes nothing and is emitted
19
- `()` — except the variadic few listed under the catalog, which take arguments the
20
- catalog never declared and so are not arity-checked at all.
7
+ `withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed. Arity:
8
+
9
+ - A declared argument list (the catalog below) is an EXACT count, not a floor: passing more
10
+ THROWS, in the type and at runtime.
11
+ - Seven declared filters take more: `concat` (trailing separator), `index_by` (trailing list
12
+ flag), `get` (trailing variable map), `array_merge`/`array_merge_recursive` (any number of
13
+ arrays), `jwe_encode`, `jwe_decode`.
14
+ - A filter with NO declared list is called `fl.<name>()`; passing an argument is a compile
15
+ error. The variadic filters at the end of the catalog take undeclared arguments and are
16
+ not arity-checked.
17
+ - Past any of these — a filter the catalog under-declares, or more than a
18
+ zero-argument filter's `()` accepts — use the untyped `filter("name", …)`.
19
+
21
20
  A typed filter also accepts one object of NAMED arguments (`fl.add({ value: 1 })`); a key
22
21
  the filter does not declare throws rather than being dropped.
23
22
  A bare JS **scalar** — string, number or boolean — is accepted in ANY `fl.*` argument and
24
- wrapped as the constant you would have written by hand (`fl.get("a.b", 0)` encodes
25
- identically to `fl.get(c.text("a.b"), c.int(0))`). An object or array must still be built
26
- with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
27
- `withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
28
- chain, so compute it in a prior `set_var`. The arg types below name each argument's
29
- ENGINE type, not the JS type you may pass.
30
- `fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`, not
31
- `6.0`) and give a decimal only when either operand is one — the `decimal` return type
32
- below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
23
+ wrapped as a constant (`fl.get("a.b", 0)` ≡ `fl.get(c.text("a.b"), c.int(0))`). Build an
24
+ object or array with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`,
25
+ a `withFilters` chain); inside `obj()`/`expr()` an argument cannot carry its own filter
26
+ chain — compute it in a prior `set_var`. Arg types below are ENGINE types, not JS types.
27
+ `fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`) and give
28
+ a decimal when either is one; an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
33
29
  when it divides exactly.
34
30
  To add to a numeric column (counter, stock, balance), use `s.db.increment`
35
31
  (`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
36
32
  atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the
37
33
  stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get` the row
38
34
  `as: "current"`, then `withFilters(ref("current.clicks"), fl.add(c.int(1)))`.
35
+ ⚠ NULL operands, by filter:
36
+ - Text filters (`trim`/`upper`/`strlen`/`to_int`/…) pass null through (`strlen(null)` is `null`;
37
+ `strlen` of a non-string is `null` too, not a length).
38
+ - Arithmetic treats null as `0` (`null|add:1` → `1`).
39
+ - `fl.concat` on a null or list base returns `""` and SILENTLY DROPS its argument
40
+ (`null|concat:"x"` → `""`). Default the base first:
41
+ `withFilters(inp("middle"), fl.first_notnull(c.text("")), fl.concat("x"))`.
42
+ - `fl.split` of null is `[""]`.
43
+
44
+ ⚠ `fl.trim`/`ltrim`/`rtrim` (and the `s.text.*` trims) take `mask` as a SET OF CHARACTERS, not a
45
+ substring. It is a PHP MASK, so `"a..c"` means the RANGE a-c, not the three characters `a`, `.`, `c`.
39
46
 
40
47
  - `fl.add(value: decimal): decimal`
41
48
  - `fl.append(value: <T>, path: text): <T>[]`
@@ -57,7 +64,7 @@ stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get
57
64
  - `fl.array_set(path: text, value: any): obj` — sets a DOTTED path and returns the value; a non-object piped value is replaced by an empty one
58
65
  - `fl.array_slice(offset: int, length?: int): <T>[]`
59
66
  - `fl.array_unshift(value: <T>): <T>[]`
60
- - `fl.array_upmerge(match: obj, node: obj): <T>[]` — merges the node INTO each matched element; `array_replace` swaps the element whole
67
+ - `fl.array_upmerge(match: obj, node: obj): <T>[]` — merges the node into the FIRST matched element, and APPENDS it on a miss (an UPSERT, not update-all) — use `fl.map` to update every match; `array_replace` is first-match too but swaps the element whole and THROWS on a miss
61
68
  - `fl.base_convert(from_base: any, to_base: any): text`
62
69
  - `fl.bitwise_and(value: int): int`
63
70
  - `fl.bitwise_or(value: int): int`
@@ -79,32 +86,32 @@ stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get
79
86
  - `fl.decrypt(algorithm: enum, key: text, iv: text): text`
80
87
  - `fl.detect_encoding(encodings?: text): text`
81
88
  - `fl.div(value: decimal): decimal`
82
- - `fl.encrypt(algorithm: enum, key: text, iv: text): text`
89
+ - `fl.encrypt(algorithm: enum, key: text, iv: text): text` — binds RAW ciphertext bytes — fl.base64_encode() before returning or storing (fl.decrypt takes the raw bytes back)
83
90
  - `fl.ends_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
84
91
  - `fl.epochms_add_ms(milliseconds: int): epochms`
85
92
  - `fl.epochms_add_secs(seconds: int): epochms`
86
93
  - `fl.epochms_date(format: text, timezone?: text): text`
87
94
  - `fl.epochms_from_format(format: text, timezone?: text): text`
88
- - `fl.epochms_transform(format: text, timezone?: text): text` — applies a relative shift (e.g. "+1 day") to the timestamp
95
+ - `fl.epochms_transform(format: text, timezone?: text): int` — applies a relative shift (e.g. "+1 day") to the timestamp. ⚠ a format `strtotime` cannot parse yields `0`, and a MISTYPED one (`"+1 dya"`) a PLAUSIBLE WRONG time, both with NO error — see date-filter failure modes in `llms/statements-runtime.md`
89
96
  - `fl.eq(value: <T>): bool`
90
- - `fl.every(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent`
97
+ - `fl.every(code: text, timeout?: int): bool` — `code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent` — returns a BOOL (`true` on an empty list)
91
98
  - `fl.filter(code: text, timeout?: int): any[]` — `code` is a JS body run per element (keep it? true/false), over `$this`/`$index`/`$parent`
92
- - `fl.filter_empty(path?: text): <T>[]` — keeps entries that are not empty ("", null, 0, "0", false, [], {})
99
+ - `fl.filter_empty(path?: text): <T>[]` — keeps entries that are not empty ("", null, 0, "0", false, [], {}) — the only one of the family that drops them all
93
100
  - `fl.filter_empty_array(path?: text): <T>[]`
94
101
  - `fl.filter_empty_object(path?: text): <T>[]`
95
- - `fl.filter_empty_text(path?: text): <T>[]`
102
+ - `fl.filter_empty_text(path?: text): <T>[]` — drops only `""`; null, 0, false, [] and {} stay
96
103
  - `fl.filter_false(path?: text): <T>[]`
97
104
  - `fl.filter_null(path?: text): <T>[]`
98
- - `fl.filter_zero(path?: text): <T>[]`
99
- - `fl.find(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first element it accepts
100
- - `fl.findIndex(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first matching index
105
+ - `fl.filter_zero(path?: text): <T>[]` — drops only the integer `0` (strict), not `"0"` or `0.0`
106
+ - `fl.find(code: text, timeout?: int): <T>` — `code` is a JS body run per element; returns the first ELEMENT it accepts (`null` when none)
107
+ - `fl.findIndex(code: text, timeout?: int): int` — `code` is a JS body run per element; returns the first matching INDEX as an int (`-1` when none)
101
108
  - `fl.first_notempty(value: any): any` — first value that is not empty ("", null, 0, "0", false, [], {})
102
109
  - `fl.first_notnull(value: any): any`
103
- - `fl.fsort(path?: text, type?: "text"|"itext"|"natural"|"inatural"|"number", asc?: bool): <T>[]` — `type` is the comparator, and ONLY "number" compares numerically — "text"/"itext" are strcmp/strcasecmp, "natural"/"inatural" are the human-readable "a2 < a10" orderings. Default "itext". Anything else silently sorts as text, so a numeric sort MUST spell "number"; the path arg drills into each element
104
- - `fl.get(path: text, default?: json): any` — `path` may be a runtime value: after `fl.index_by("suite_id")`, `fl.get(ref("suite.id"))` returns that key's rows (null for a missing key)
110
+ - `fl.fsort(path?: text, type?: "text"|"itext"|"natural"|"inatural"|"number", asc?: bool): <T>[]` — `type` is the comparator: "number" (the only numeric one), "text"/"itext" (strcmp/strcasecmp), "natural"/"inatural" ("a2 < a10"). Default "itext"; anything else sorts as text. The path arg drills into each element
111
+ - `fl.get(path: text, default?: json): any` — `path` may be a runtime value: after `fl.index_by("suite_id")`, `fl.get(ref("suite.id"))` returns that key's rows (null for a missing key). ⚠ the `default` applies only to a MISSING path — a key present with a `null` value stays `null`; chain `fl.first_notnull(default)` to cover both.
105
112
  - `fl.gt(value: <T>): bool`
106
113
  - `fl.gte(value: <T>): bool`
107
- - `fl.has(path: text): bool`
114
+ - `fl.has(path: text): bool` — `false` for a missing key and for a key whose value is `null` (unlike `fl.get`'s default, which treats a present null as present)
108
115
  - `fl.hmac_md5(key: text, raw?: bool): text`
109
116
  - `fl.hmac_sha1(key: text, raw?: bool): text`
110
117
  - `fl.hmac_sha256(key: text, raw?: bool): text`
@@ -137,32 +144,32 @@ stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get
137
144
  - `fl.pow(exp: <T>): decimal`
138
145
  - `fl.prepend(value: <T>, path: text): <T>[]`
139
146
  - `fl.range(start: int, stop: int): int[]`
140
- - `fl.reduce(initial_value: int, code: text, timeout?: int): any[]` — `code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED — omitting it would slot the code as the initial value
147
+ - `fl.reduce(initial_value: any, code: text, timeout?: int): any` — `code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED. `initial_value` takes ANY value (an object/text accumulator, `c.obj({...})`/`c.text("")`, not just an int); the result is that accumulator
141
148
  - `fl.regex_match(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
142
149
  - `fl.regex_match_all(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
143
150
  - `fl.regex_quote(delimiter?: text): text`
144
151
  - `fl.regex_replace(replacement: text, subject: text): text` — piped value is the PATTERN, `subject` is the text searched — see `regex_test`. The replacement comes FIRST
145
- - `fl.regex_test(subject: text): bool` — piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject — the REVERSE of `contains`/`starts_with`. Swapped, it answers false for every input with no error, so write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time
152
+ - `fl.regex_test(subject: text): bool` — piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject — the REVERSE of `contains`/`starts_with`. Swapped args → always false, no error. Write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time
146
153
  - `fl.round(precision?: int): decimal`
147
154
  - `fl.rtrim(mask?: text): text`
148
- - `fl.secureid_decode(salt: text): int`
149
- - `fl.secureid_encode(salt: text): text`
155
+ - `fl.secureid_decode(salt: text): int` — a wrong salt, or a garbage/empty id, is a 400 (`This signature is invalid.` / `Invalid input format for secureId.`), NOT null — wrap in s.try_catch to handle a miss; only the id from `secureid_encode` of a non-negative int round-trips back
156
+ - `fl.secureid_encode(salt: text): text` — the operand must be a NON-NEGATIVE integer — a negative or fractional one encodes without error but `secureid_decode` returns a DIFFERENT positive int (`-3` → `13`, `-42` → `214`, `1.5` → `1`), NOT a round-trip; validate the domain before encoding
150
157
  - `fl.set(path: text, value: any): any`
151
158
  - `fl.set_conditional(path: text, value: any, conditional: any): any`
152
159
  - `fl.set_ifnotempty(path: text, value: any): any`
153
160
  - `fl.set_ifnotnull(path: text, value: any): any`
154
161
  - `fl.sha1(raw?: bool): text`
155
- - `fl.sha256(raw?: bool): text`
162
+ - `fl.sha256(raw?: bool): text` — the optional `raw` arg returns RAW binary, not the hex digest — fl.bin2hex()/fl.base64_encode() it before returning or storing (strlen then UNDER-COUNTS: it counts characters, not bytes); omit `raw` for hex
156
163
  - `fl.sha384(raw?: bool): text`
157
164
  - `fl.sha512(raw?: bool): text`
158
- - `fl.some(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent`
165
+ - `fl.some(code: text, timeout?: int): bool` — `code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent` — returns a BOOL (`false` on an empty list)
159
166
  - `fl.splice(offset: int, length?: int, path?: text): <T>[]` — returns the REMOVED slice, not the remainder — [1,2,3,4] spliced at offset 1 length 2 yields [2,3]; with a `path` it removes in place and returns the whole value instead
160
167
  - `fl.split(separator: text): text[]`
161
168
  - `fl.starts_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
162
169
  - `fl.string_replace(search: text, replacement: text): text`
163
170
  - `fl.strip_tags(exclude?: text): text`
164
- - `fl.stripos(search: text): int`
165
- - `fl.strpos(search: text): int`
171
+ - `fl.stripos(search: text): int|false`
172
+ - `fl.strpos(search: text): int|false`
166
173
  - `fl.sub(value: decimal): decimal`
167
174
  - `fl.substr(start: int, length: int): text`
168
175
  - `fl.to_epoch_day(timezone?: text): int`
@@ -173,16 +180,18 @@ stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get
173
180
  - `fl.to_epochms(timezone?: text): epochms`
174
181
  - `fl.transform(expression: text): any` — `expression` is Xano Expression Engine source, NOT a JS body — no `return`, and the piped value is `$0` (or `$$`), NOT `$this` (which is null here). `$var`/`$input`/`$env`/`$auth` resolve and filters pipe inside it: `$0 * 2`, `$0|sort|join:","`. Parenthesize a pipe inside an object literal — `{ s: ($0|sort|join:",") }` — or its comma is read as the key separator and later keys vanish silently. For JavaScript use `lambda`
175
182
  - `fl.trim(mask?: text): text`
176
- - `fl.unique(path?: text): <T>[]`
183
+ - `fl.unique(path?: text): <T>[]` — with a `path`, dedupes a list of records by the value at that path and keeps the FIRST per key — but it DROPS every element whose path is missing or null (the same rule as `index_by`), so deduping by an optional key loses those rows
177
184
  - `fl.unpick(keys: text): <T>` — returns the object without the named keys (inverse of a pick)
178
185
  - `fl.unset(path: text): any`
179
186
  - `fl.url_addarg(key: text, value: text, encoding_rfc3986?: bool): text`
180
187
  - `fl.url_delarg(key: text): text`
181
188
  - `fl.url_getarg(key: text, default?: text): text`
182
- - `fl.url_hasarg(key: text): text`
189
+ - `fl.url_hasarg(key: text): bool`
183
190
  - `fl.yaml_encode(options?: bool, inline?: int, indent?: int): text`
184
191
 
185
- Zero-argument filters, by operand type — call as `fl.<name>()`; an argument is a compile error. array: array_entries, array_keys, array_lower, array_pop, array_shift, array_shuffle, array_values, count, first, flatten, last, reverse, rsort, safe_array; comparison: bitwise_not, empty, even, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, not, odd; geo: to_geo_linestring, to_geo_multilinestring, to_geo_multipoint, to_geo_multipolygon, to_geo_point, to_geo_polygon; math: abs, acos, acosh, asin, asinh, atan, atanh, avg, ceil, cos, deg2rad, exp, floor, ln, log10, product, rad2deg, sin, sqrt, sum, tan; misc: null; other: sort; security: uid, uuid4; text: addslashes, capitalize, escape, from_utf8, list_encodings, lower, querystring_parse, sql_alias, sql_esc, strip_accents, strlen, text_escape, text_unescape, to_utf8, upper, url_parse; timestamp: ms_to_secs, secs_to_ms; transform: base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, create_object_from_entries, decbin, dechex, decoct, hex2bin, hexdec, json_decode, json_encode, octdec, to_bool, to_decimal, to_expr, to_int, to_text, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, xml_decode, yaml_decode.
192
+ Zero-argument filters, by operand type: array: array_entries, array_keys, array_lower, array_pop, array_shift, array_shuffle, array_values, count, first, flatten, last, reverse, rsort, safe_array; comparison: empty, even, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, not, null, odd; geo: to_geo_linestring, to_geo_multilinestring, to_geo_multipoint, to_geo_multipolygon, to_geo_point, to_geo_polygon; math: abs, acos, acosh, asin, asinh, atan, atanh, avg, bitwise_not, ceil, cos, deg2rad, exp, floor, ln, log10, product, rad2deg, sin, sqrt, sum, tan; other: sort; security: uid, uuid4; text: addslashes, capitalize, escape, from_utf8, list_encodings, lower, querystring_parse, sql_alias, sql_esc, strip_accents, strlen, text_escape, text_unescape, to_utf8, upper, url_parse; timestamp: ms_to_secs, secs_to_ms; transform: base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, create_object_from_entries, decbin, dechex, decoct, hex2bin, hexdec, json_decode, json_encode, octdec, to_bool, to_decimal, to_expr, to_int, to_text, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, xml_decode, yaml_decode.
186
193
  `fl.reverse()` reverses a list only: on a text value it answers the text UNCHANGED, with no error.
194
+ An unknown `timezone` (a typo, `+05:30`, `PDT`) silently means UTC. A literal warns at export; take a runtime zone as an `input.enum`.
195
+ `fl.to_bool()` is NOT a truthiness cast: it accepts only the boolean vocabulary — `true`/`1`/`"1"`/`"true"`/`"on"`/`"yes"` and `false`/`0`/`"0"`/`"false"`/`"off"`/`""` — and ANY other value 400s `ERROR_CODE_INPUT_ERROR` "Invalid boolean input.". For a truthiness cast pipe `fl.ne(c.int(0))`.
187
196
 
188
197
  Variadic filters — they take arguments, but no declared list, so the count is not checked: sprintf.
@@ -3,31 +3,32 @@
3
3
  > Read when building an MCP server (tools, prompts, resources) or an `agent()`.
4
4
 
5
5
  - An MCP server serves THREE primitives, and each reaches the client differently: a `tool()` is an action the MODEL calls (it may write); a `resource()` is read-only context the client APPLICATION lists and attaches by `uri` (reference docs, a schema, one record through a `{variable}` template); a `prompt()` is a message template with arguments the USER picks by name. Context a session opens with is a `resource()`; a workflow a user starts by name is a `prompt()`; data the model must fetch on its own mid-task stays a `tool()`, since a client shows the model only the resources attached to the conversation. Register each kind (`registerTools`/`registerPrompts`/`registerResources`) and list it on the server.
6
- - `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).
7
- - ⚠ Refuses any request carrying a browser `Origin`, preflight too: 403, JSON-RPC `-32000` `Forbidden: Origin not allowed`. One with no `Origin` (curl, a server, an MCP client) is served; the bundle cannot admit an origin, so call it server-side, never from browser JS.
8
- - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) is the LEGACY way to publish a tool as an MCP resource — author a `resource()` and list it in `resources` instead; `toolMeta` is extra metadata on a tool entry. The two payload fields are per-type and supplying the other one is refused, because the engine stores it against neither. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — per-tool, and the only gate there is. ⚠ It is also what gives the tool a CALLER, on an `agent()` exactly as on an MCP server. `auth()` inside a tool whose entry names no table does NOT return null: the call answers a normal result carrying `{"code":"ERROR_FATAL","message":""}`, so the model reads a successful tool result and reports success while nothing is written. A caller token does not rescue it — the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.
6
+ - `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).
7
+ - ⚠ The endpoint is CORS-open (serves every browser `Origin`; preflight `204`, `access-control-allow-origin: *`); per-tool `auth`/`oauth` is the only gate.
8
+ - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) publishes a tool as an MCP resource — prefer a `resource()` listed in `resources`; `toolMeta` is extra metadata on a tool entry. `resourceUri` only with `type: "resource"`, `toolMeta` only with `type: "tool"`; the wrong one is refused. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — per-tool, and the only gate there is. ⚠ It is also what gives the tool a CALLER, on an `agent()` and an MCP server alike. `auth()` inside a tool whose entry names no table does NOT return null: the run binds `{"code":"ERROR_FATAL","message":""}`. On an `agent()` the model reads that as a successful tool result and reports success while nothing is written; over an MCP server's `tools/call` the client instead gets an `isError: true` tool error with the generic text `Unable to get successful response from executing tool`. Either way the write never happens and a caller token does not rescue it — the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.
9
9
  - `prompts?` / `resources?`: `prompt()` / `resource()` HANDLES (or names), or a `{ prompt, enabled?, auth? }` / `{ resource, enabled?, auth? }` wrapper. `auth` names the auth table and is what gives the stack a caller: a prompt/resource reading `auth()` behind an entry with none answers every `prompts/get` / `resources/read` with `-32603 "Access Denied"` (`export()` warns `toolset.primitive-reads-auth-ungated`). Listing one target twice THROWS; two resources with one `uri` on one server fail `export()` (`mcp.resource-uri-duplicate`). MCP-server only — `agent()` takes tools only.
10
10
  - `history?` is the server tier for its tools, prompts AND resources alike; an object's own `history` wins. The workspace tier (`workspaceConfig({ history })`) has `prompt` and `resource` keys, both default on.
11
11
  - `oauth?`: per-server sign-in; omit and nothing changes. Union on `mode`; `authTable` (REQUIRED, auth `table()` handle or name) is whose row the signed-in user is — `auth()` on the whole server, `t.auth` in its trigger. Hosted (the platform is the authorization server): `{ mode: "hosted", authTable, loginUrl }` — clients are sent to `loginUrl` (YOUR page, which is also the consent screen) with `mcp_request`; show `s.mcp.oauth.request`, sign the user in, then your endpoint calls `s.mcp.oauth.complete` with their `decision` and the page redirects to the URL it binds. External (your IdP issues tokens): `{ mode: "external", authTable, issuer, column, audience?, audienceAck?, claim?, claimAck?, preset?, allowedClientIds? }` — token `claim` (default `sub`) matched against `column`; `preset` is `auth0|clerk|workos|entra|okta|cognito|generic`. `loginUrl`/`issuer`/`audience` take `env("NAME")` (resolved per environment).
12
- - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` — users can edit it at most providers). Unknown `mode`/`preset` THROWS; so do the dropped `consent`/`branding`/`trustedClients`.
12
+ - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` — users can edit it at most providers). Unknown `mode`/`preset` THROWS, as do `consent`/`branding`/`trustedClients` (not options).
13
13
  - `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order, `content` a string or an MCP content block: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
14
14
  - `resource({ name, uri, guid?, description?, docs?, mimeType?, title?, icons?, annotations?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP resource; takes `registerResources`. Clients address it by `uri`, never `name`.
15
15
  - `uri`: a literal (`"docs://readme"`, no `input`) or an RFC 6570 LEVEL-1 template (`"orders://{region}/{order_id}"`). It must start with a scheme; each `{variable}` is letters/digits/`_`, one per brace pair, never two adjacent. `input` must be EXACTLY the template's variables, each a single `text`/`int`/`decimal`/`bool`/`enum`/`email`/`uuid` — anything else THROWS. A value that does not convert is refused before the stack runs.
16
16
  - `response`: a string is returned as text; non-UTF-8 content (a file, binary) as a base64 blob. `mimeType?` omitted → derived from what the stack returns.
17
+ - Not found: a resource has no built-in miss path. Returning a `db.get` result straight through on a miss is an EMPTY SUCCESS — the client attaches an empty document (`text: ""`, `mimeType: "text/plain"`), not an error. Gate it: `s.precondition({ expr: expr(ref("note"), "!=", c.null()), error_type: "notfound", error: c.text("no such note") })` gives a real `resources/read` error (JSON-RPC `-32602`), but ⚠ the AUTHORED message is dropped — the client sees only the generic `Not Found` (unlike a `tool()` precondition).
17
18
  - `annotations?`: `{ audience?: ("user" | "assistant")[], priority?: 0..1, lastModified?: ISO 8601 string }`.
18
19
  - MCP metadata, on `tool`/`prompt`/`resource`: `title?` (display name clients show instead of `name`); `icons?: { src, mimeType?, sizes?, theme? }[]` — `src` is `https:` (≤ 2048 chars), a base64 `data:` URI of PNG/JPEG/WebP (≤ 64 KiB), or `hostedFile("./icon.png", import.meta.url)`, a repo file served at each backend's own absolute URL (a pull keeps the `/vault/…` path); SVG, `http:` and every other scheme THROW; `mimeType` is `image/png|jpeg|webp`, `sizes` a list (`["48x48"]`, `["any"]`), `theme` `light|dark`. Tool only: `annotations?: { readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` — hints; an unset one is derived by the platform — and `output?`, a structured-output schema in the `input` grammar: a returned plain object then reaches the client as `structuredContent` plus a text copy, and a result that does not match is a tool error naming the field.
19
20
  - `s.mcp.elicit({ key, message, input?, as? })` — ask the MCP client's user mid-call; binds `{ action: "accept" | "decline" | "cancel", content? }` (`content` only on accept, keyed by the `input` field names). `key`: a stable name unique in the stack; `message`: string or value. `input` is the form: a FLAT set of `text`/`email`/`date`/`int`/`decimal`/`bool`/`enum` fields (an enum may be a list); nested objects, files, JSON, timestamps, `password` and `sensitive` fields THROW. Works in tool, prompt and resource stacks.
20
21
  - ⚠ The WHOLE stack re-runs from the top when the user answers — everything BEFORE an elicit runs once per round trip, so ASK FIRST, then act. A write before an elicit (`s.db.*` writes, raw SQL, a non-GET `s.api.request`, `s.util.send_email`, `s.function.run`/`.call`, `s.tool.call`) makes `export()` warn `mcp.write-before-elicit`; accept a deliberate one per def with `diagnostics: { allow: ["mcp.write-before-elicit"] }`. An elicit inside `s.db.transaction` commits the transaction's earlier writes on every round trip.
21
- - Input is collected only from clients on MCP `2026-07-28` or later that declare form elicitation. Every other caller — an older client, a debug run, an agent, a workflow test — gets `{ action: "cancel" }` and the stack carries on, so ALWAYS handle `cancel`. A runtime error inside an async function run.
22
+ - Input is collected only from clients on MCP `2026-07-28` or later that declare form elicitation. Every other caller — an older client, a debug run, an agent, a workflow test — gets `{ action: "cancel" }` and the stack carries on, so ALWAYS handle `cancel`. Inside an async function run, `s.mcp.elicit` is a runtime error.
22
23
  - `s.mcp.progress({ progress, total?, message? })` — report progress to a client that asked for it (a no-op otherwise); values never go backwards (a lower `progress` is sent as the last one).
23
24
  - `s.mcp.oauth.complete({ request, decision, unsafe_user_id?, as? })` — run by the endpoint your `loginUrl` page calls after sign-in; `request` is the page's `mcp_request`. Signs in the CALLER (`auth()`, an `authTable` row whose session token is under 10 minutes old) and binds the single-use URL (text) to redirect to. `decision` (`"approve" | "deny"`, REQUIRED) is what the user chose on your page. ⚠ `unsafe_user_id` names the row directly, skipping the caller checks — anyone reaching that endpoint signs in as that user.
24
25
  - `s.mcp.oauth.request({ request, as? })` — a pending sign-in's verified details for your `loginUrl` page to show before the user approves: `{ client_name, client_logo, callback_host, client_verified, server_name }`. Does not consume it.
25
26
  - `s.mcp.oauth.revoke({ mcp_server, user_id? | grant_id? | all?, as? })` — end hosted sign-ins on a server: EXACTLY ONE of `user_id`, `grant_id`, `all: c.bool(true)`, else `export()` fails (`mcp.oauth-revoke-target`). Binds `{ revoked }`.
26
27
  - `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` — an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` — the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.
27
- - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
28
+ - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (mutually exclusive; both is a type error and throws); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
28
29
  - `xano-free` runs only on Xano's cloud: on the Xano Engine on this machine a run fails `ERROR_FATAL` `The free model is not available in this process.` — use a keyed provider there.
29
- - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
30
- - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
31
- - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, allowToolExecution: c.bool(true), as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. ⚠ An agent with tools needs `allowToolExecution: c.bool(true)` on the run: unset, its tools are OFF and it answers without them (warns `stack.agent-tools-off`).
30
+ - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` needs the wrapper naming its auth table (see `mcpServer`'s `tools?`).
31
+ - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. With `tools`, the run executes them first, then shapes its answer into the schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map. e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed from this schema; `resultShape` only overrides that, or types an agent referenced by bare name.
32
+ - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. `allowToolExecution` defaults to true. ⚠ `c.bool(false)` does not hide the tools: the model still emits a call, the call never executes, and the run ends with an empty `result` (warns `stack.agent-tools-off`).
32
33
  - **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `npx @xano/sdk marketplace search <q>`.
33
34
  - Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.