@oobe-protocol-labs/synapse-sap-sdk 0.1.0

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 (315) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +882 -0
  3. package/dist/cjs/constants/index.js +43 -0
  4. package/dist/cjs/constants/index.js.map +1 -0
  5. package/dist/cjs/constants/limits.js +161 -0
  6. package/dist/cjs/constants/limits.js.map +1 -0
  7. package/dist/cjs/constants/programs.js +78 -0
  8. package/dist/cjs/constants/programs.js.map +1 -0
  9. package/dist/cjs/constants/seeds.js +57 -0
  10. package/dist/cjs/constants/seeds.js.map +1 -0
  11. package/dist/cjs/core/client.js +391 -0
  12. package/dist/cjs/core/client.js.map +1 -0
  13. package/dist/cjs/core/connection.js +319 -0
  14. package/dist/cjs/core/connection.js.map +1 -0
  15. package/dist/cjs/core/index.js +24 -0
  16. package/dist/cjs/core/index.js.map +1 -0
  17. package/dist/cjs/errors/index.js +334 -0
  18. package/dist/cjs/errors/index.js.map +1 -0
  19. package/dist/cjs/events/index.js +136 -0
  20. package/dist/cjs/events/index.js.map +1 -0
  21. package/dist/cjs/idl/index.js +63 -0
  22. package/dist/cjs/idl/index.js.map +1 -0
  23. package/dist/cjs/idl/synapse_agent_sap.json +9710 -0
  24. package/dist/cjs/index.js +147 -0
  25. package/dist/cjs/index.js.map +1 -0
  26. package/dist/cjs/modules/agent.js +272 -0
  27. package/dist/cjs/modules/agent.js.map +1 -0
  28. package/dist/cjs/modules/attestation.js +147 -0
  29. package/dist/cjs/modules/attestation.js.map +1 -0
  30. package/dist/cjs/modules/base.js +128 -0
  31. package/dist/cjs/modules/base.js.map +1 -0
  32. package/dist/cjs/modules/escrow.js +246 -0
  33. package/dist/cjs/modules/escrow.js.map +1 -0
  34. package/dist/cjs/modules/feedback.js +166 -0
  35. package/dist/cjs/modules/feedback.js.map +1 -0
  36. package/dist/cjs/modules/index.js +35 -0
  37. package/dist/cjs/modules/index.js.map +1 -0
  38. package/dist/cjs/modules/indexing.js +375 -0
  39. package/dist/cjs/modules/indexing.js.map +1 -0
  40. package/dist/cjs/modules/ledger.js +234 -0
  41. package/dist/cjs/modules/ledger.js.map +1 -0
  42. package/dist/cjs/modules/tools.js +319 -0
  43. package/dist/cjs/modules/tools.js.map +1 -0
  44. package/dist/cjs/modules/vault.js +410 -0
  45. package/dist/cjs/modules/vault.js.map +1 -0
  46. package/dist/cjs/pda/index.js +377 -0
  47. package/dist/cjs/pda/index.js.map +1 -0
  48. package/dist/cjs/plugin/index.js +934 -0
  49. package/dist/cjs/plugin/index.js.map +1 -0
  50. package/dist/cjs/plugin/protocols.js +282 -0
  51. package/dist/cjs/plugin/protocols.js.map +1 -0
  52. package/dist/cjs/plugin/schemas.js +831 -0
  53. package/dist/cjs/plugin/schemas.js.map +1 -0
  54. package/dist/cjs/postgres/adapter.js +715 -0
  55. package/dist/cjs/postgres/adapter.js.map +1 -0
  56. package/dist/cjs/postgres/index.js +50 -0
  57. package/dist/cjs/postgres/index.js.map +1 -0
  58. package/dist/cjs/postgres/serializers.js +381 -0
  59. package/dist/cjs/postgres/serializers.js.map +1 -0
  60. package/dist/cjs/postgres/sync.js +221 -0
  61. package/dist/cjs/postgres/sync.js.map +1 -0
  62. package/dist/cjs/postgres/types.js +44 -0
  63. package/dist/cjs/postgres/types.js.map +1 -0
  64. package/dist/cjs/registries/builder.js +414 -0
  65. package/dist/cjs/registries/builder.js.map +1 -0
  66. package/dist/cjs/registries/discovery.js +362 -0
  67. package/dist/cjs/registries/discovery.js.map +1 -0
  68. package/dist/cjs/registries/index.js +51 -0
  69. package/dist/cjs/registries/index.js.map +1 -0
  70. package/dist/cjs/registries/session.js +433 -0
  71. package/dist/cjs/registries/session.js.map +1 -0
  72. package/dist/cjs/registries/x402.js +577 -0
  73. package/dist/cjs/registries/x402.js.map +1 -0
  74. package/dist/cjs/types/accounts.js +13 -0
  75. package/dist/cjs/types/accounts.js.map +1 -0
  76. package/dist/cjs/types/common.js +13 -0
  77. package/dist/cjs/types/common.js.map +1 -0
  78. package/dist/cjs/types/enums.js +174 -0
  79. package/dist/cjs/types/enums.js.map +1 -0
  80. package/dist/cjs/types/index.js +36 -0
  81. package/dist/cjs/types/index.js.map +1 -0
  82. package/dist/cjs/types/instructions.js +92 -0
  83. package/dist/cjs/types/instructions.js.map +1 -0
  84. package/dist/cjs/utils/hash.js +58 -0
  85. package/dist/cjs/utils/hash.js.map +1 -0
  86. package/dist/cjs/utils/index.js +27 -0
  87. package/dist/cjs/utils/index.js.map +1 -0
  88. package/dist/cjs/utils/serialization.js +105 -0
  89. package/dist/cjs/utils/serialization.js.map +1 -0
  90. package/dist/cjs/utils/validation.js +36 -0
  91. package/dist/cjs/utils/validation.js.map +1 -0
  92. package/dist/esm/constants/index.js +29 -0
  93. package/dist/esm/constants/index.js.map +1 -0
  94. package/dist/esm/constants/limits.js +158 -0
  95. package/dist/esm/constants/limits.js.map +1 -0
  96. package/dist/esm/constants/programs.js +75 -0
  97. package/dist/esm/constants/programs.js.map +1 -0
  98. package/dist/esm/constants/seeds.js +54 -0
  99. package/dist/esm/constants/seeds.js.map +1 -0
  100. package/dist/esm/core/client.js +384 -0
  101. package/dist/esm/core/client.js.map +1 -0
  102. package/dist/esm/core/connection.js +315 -0
  103. package/dist/esm/core/connection.js.map +1 -0
  104. package/dist/esm/core/index.js +19 -0
  105. package/dist/esm/core/index.js.map +1 -0
  106. package/dist/esm/errors/index.js +325 -0
  107. package/dist/esm/errors/index.js.map +1 -0
  108. package/dist/esm/events/index.js +132 -0
  109. package/dist/esm/events/index.js.map +1 -0
  110. package/dist/esm/idl/index.js +57 -0
  111. package/dist/esm/idl/index.js.map +1 -0
  112. package/dist/esm/idl/synapse_agent_sap.json +9710 -0
  113. package/dist/esm/index.js +70 -0
  114. package/dist/esm/index.js.map +1 -0
  115. package/dist/esm/modules/agent.js +268 -0
  116. package/dist/esm/modules/agent.js.map +1 -0
  117. package/dist/esm/modules/attestation.js +143 -0
  118. package/dist/esm/modules/attestation.js.map +1 -0
  119. package/dist/esm/modules/base.js +124 -0
  120. package/dist/esm/modules/base.js.map +1 -0
  121. package/dist/esm/modules/escrow.js +242 -0
  122. package/dist/esm/modules/escrow.js.map +1 -0
  123. package/dist/esm/modules/feedback.js +162 -0
  124. package/dist/esm/modules/feedback.js.map +1 -0
  125. package/dist/esm/modules/index.js +23 -0
  126. package/dist/esm/modules/index.js.map +1 -0
  127. package/dist/esm/modules/indexing.js +371 -0
  128. package/dist/esm/modules/indexing.js.map +1 -0
  129. package/dist/esm/modules/ledger.js +230 -0
  130. package/dist/esm/modules/ledger.js.map +1 -0
  131. package/dist/esm/modules/tools.js +315 -0
  132. package/dist/esm/modules/tools.js.map +1 -0
  133. package/dist/esm/modules/vault.js +406 -0
  134. package/dist/esm/modules/vault.js.map +1 -0
  135. package/dist/esm/pda/index.js +357 -0
  136. package/dist/esm/pda/index.js.map +1 -0
  137. package/dist/esm/plugin/index.js +927 -0
  138. package/dist/esm/plugin/index.js.map +1 -0
  139. package/dist/esm/plugin/protocols.js +279 -0
  140. package/dist/esm/plugin/protocols.js.map +1 -0
  141. package/dist/esm/plugin/schemas.js +828 -0
  142. package/dist/esm/plugin/schemas.js.map +1 -0
  143. package/dist/esm/postgres/adapter.js +678 -0
  144. package/dist/esm/postgres/adapter.js.map +1 -0
  145. package/dist/esm/postgres/index.js +27 -0
  146. package/dist/esm/postgres/index.js.map +1 -0
  147. package/dist/esm/postgres/serializers.js +362 -0
  148. package/dist/esm/postgres/serializers.js.map +1 -0
  149. package/dist/esm/postgres/sync.js +217 -0
  150. package/dist/esm/postgres/sync.js.map +1 -0
  151. package/dist/esm/postgres/types.js +41 -0
  152. package/dist/esm/postgres/types.js.map +1 -0
  153. package/dist/esm/registries/builder.js +410 -0
  154. package/dist/esm/registries/builder.js.map +1 -0
  155. package/dist/esm/registries/discovery.js +358 -0
  156. package/dist/esm/registries/discovery.js.map +1 -0
  157. package/dist/esm/registries/index.js +44 -0
  158. package/dist/esm/registries/index.js.map +1 -0
  159. package/dist/esm/registries/session.js +429 -0
  160. package/dist/esm/registries/session.js.map +1 -0
  161. package/dist/esm/registries/x402.js +573 -0
  162. package/dist/esm/registries/x402.js.map +1 -0
  163. package/dist/esm/types/accounts.js +12 -0
  164. package/dist/esm/types/accounts.js.map +1 -0
  165. package/dist/esm/types/common.js +12 -0
  166. package/dist/esm/types/common.js.map +1 -0
  167. package/dist/esm/types/enums.js +171 -0
  168. package/dist/esm/types/enums.js.map +1 -0
  169. package/dist/esm/types/index.js +25 -0
  170. package/dist/esm/types/index.js.map +1 -0
  171. package/dist/esm/types/instructions.js +89 -0
  172. package/dist/esm/types/instructions.js.map +1 -0
  173. package/dist/esm/utils/hash.js +53 -0
  174. package/dist/esm/utils/hash.js.map +1 -0
  175. package/dist/esm/utils/index.js +19 -0
  176. package/dist/esm/utils/index.js.map +1 -0
  177. package/dist/esm/utils/serialization.js +98 -0
  178. package/dist/esm/utils/serialization.js.map +1 -0
  179. package/dist/esm/utils/validation.js +33 -0
  180. package/dist/esm/utils/validation.js.map +1 -0
  181. package/dist/types/constants/index.d.ts +27 -0
  182. package/dist/types/constants/index.d.ts.map +1 -0
  183. package/dist/types/constants/limits.d.ts +149 -0
  184. package/dist/types/constants/limits.d.ts.map +1 -0
  185. package/dist/types/constants/programs.d.ts +69 -0
  186. package/dist/types/constants/programs.d.ts.map +1 -0
  187. package/dist/types/constants/seeds.d.ts +61 -0
  188. package/dist/types/constants/seeds.d.ts.map +1 -0
  189. package/dist/types/core/client.d.ts +323 -0
  190. package/dist/types/core/client.d.ts.map +1 -0
  191. package/dist/types/core/connection.d.ts +279 -0
  192. package/dist/types/core/connection.d.ts.map +1 -0
  193. package/dist/types/core/index.d.ts +20 -0
  194. package/dist/types/core/index.d.ts.map +1 -0
  195. package/dist/types/errors/index.d.ts +276 -0
  196. package/dist/types/errors/index.d.ts.map +1 -0
  197. package/dist/types/events/index.d.ts +248 -0
  198. package/dist/types/events/index.d.ts.map +1 -0
  199. package/dist/types/idl/index.d.ts +70 -0
  200. package/dist/types/idl/index.d.ts.map +1 -0
  201. package/dist/types/index.d.ts +68 -0
  202. package/dist/types/index.d.ts.map +1 -0
  203. package/dist/types/modules/agent.d.ts +166 -0
  204. package/dist/types/modules/agent.d.ts.map +1 -0
  205. package/dist/types/modules/attestation.d.ts +96 -0
  206. package/dist/types/modules/attestation.d.ts.map +1 -0
  207. package/dist/types/modules/base.d.ts +126 -0
  208. package/dist/types/modules/base.d.ts.map +1 -0
  209. package/dist/types/modules/escrow.d.ts +151 -0
  210. package/dist/types/modules/escrow.d.ts.map +1 -0
  211. package/dist/types/modules/feedback.d.ts +105 -0
  212. package/dist/types/modules/feedback.d.ts.map +1 -0
  213. package/dist/types/modules/index.d.ts +24 -0
  214. package/dist/types/modules/index.d.ts.map +1 -0
  215. package/dist/types/modules/indexing.d.ts +200 -0
  216. package/dist/types/modules/indexing.d.ts.map +1 -0
  217. package/dist/types/modules/ledger.d.ts +150 -0
  218. package/dist/types/modules/ledger.d.ts.map +1 -0
  219. package/dist/types/modules/tools.d.ts +182 -0
  220. package/dist/types/modules/tools.d.ts.map +1 -0
  221. package/dist/types/modules/vault.d.ts +240 -0
  222. package/dist/types/modules/vault.d.ts.map +1 -0
  223. package/dist/types/pda/index.d.ts +296 -0
  224. package/dist/types/pda/index.d.ts.map +1 -0
  225. package/dist/types/plugin/index.d.ts +171 -0
  226. package/dist/types/plugin/index.d.ts.map +1 -0
  227. package/dist/types/plugin/protocols.d.ts +152 -0
  228. package/dist/types/plugin/protocols.d.ts.map +1 -0
  229. package/dist/types/plugin/schemas.d.ts +823 -0
  230. package/dist/types/plugin/schemas.d.ts.map +1 -0
  231. package/dist/types/postgres/adapter.d.ts +355 -0
  232. package/dist/types/postgres/adapter.d.ts.map +1 -0
  233. package/dist/types/postgres/index.d.ts +24 -0
  234. package/dist/types/postgres/index.d.ts.map +1 -0
  235. package/dist/types/postgres/serializers.d.ts +30 -0
  236. package/dist/types/postgres/serializers.d.ts.map +1 -0
  237. package/dist/types/postgres/sync.d.ts +132 -0
  238. package/dist/types/postgres/sync.d.ts.map +1 -0
  239. package/dist/types/postgres/types.d.ts +167 -0
  240. package/dist/types/postgres/types.d.ts.map +1 -0
  241. package/dist/types/registries/builder.d.ts +340 -0
  242. package/dist/types/registries/builder.d.ts.map +1 -0
  243. package/dist/types/registries/discovery.d.ts +333 -0
  244. package/dist/types/registries/discovery.d.ts.map +1 -0
  245. package/dist/types/registries/index.d.ts +48 -0
  246. package/dist/types/registries/index.d.ts.map +1 -0
  247. package/dist/types/registries/session.d.ts +323 -0
  248. package/dist/types/registries/session.d.ts.map +1 -0
  249. package/dist/types/registries/x402.d.ts +463 -0
  250. package/dist/types/registries/x402.d.ts.map +1 -0
  251. package/dist/types/types/accounts.d.ts +565 -0
  252. package/dist/types/types/accounts.d.ts.map +1 -0
  253. package/dist/types/types/common.d.ts +166 -0
  254. package/dist/types/types/common.d.ts.map +1 -0
  255. package/dist/types/types/enums.d.ts +238 -0
  256. package/dist/types/types/enums.d.ts.map +1 -0
  257. package/dist/types/types/index.d.ts +28 -0
  258. package/dist/types/types/index.d.ts.map +1 -0
  259. package/dist/types/types/instructions.d.ts +366 -0
  260. package/dist/types/types/instructions.d.ts.map +1 -0
  261. package/dist/types/utils/hash.d.ts +48 -0
  262. package/dist/types/utils/hash.d.ts.map +1 -0
  263. package/dist/types/utils/index.d.ts +19 -0
  264. package/dist/types/utils/index.d.ts.map +1 -0
  265. package/dist/types/utils/serialization.d.ts +69 -0
  266. package/dist/types/utils/serialization.d.ts.map +1 -0
  267. package/dist/types/utils/validation.d.ts +29 -0
  268. package/dist/types/utils/validation.d.ts.map +1 -0
  269. package/package.json +178 -0
  270. package/src/constants/index.ts +44 -0
  271. package/src/constants/limits.ts +165 -0
  272. package/src/constants/programs.ts +83 -0
  273. package/src/constants/seeds.ts +66 -0
  274. package/src/core/client.ts +416 -0
  275. package/src/core/connection.ts +409 -0
  276. package/src/core/index.ts +20 -0
  277. package/src/errors/index.ts +346 -0
  278. package/src/events/index.ts +335 -0
  279. package/src/idl/index.ts +76 -0
  280. package/src/idl/synapse_agent_sap.json +9710 -0
  281. package/src/index.ts +253 -0
  282. package/src/modules/agent.ts +319 -0
  283. package/src/modules/attestation.ts +168 -0
  284. package/src/modules/base.ts +158 -0
  285. package/src/modules/escrow.ts +308 -0
  286. package/src/modules/feedback.ts +186 -0
  287. package/src/modules/index.ts +24 -0
  288. package/src/modules/indexing.ts +444 -0
  289. package/src/modules/ledger.ts +262 -0
  290. package/src/modules/tools.ts +411 -0
  291. package/src/modules/vault.ts +533 -0
  292. package/src/pda/index.ts +512 -0
  293. package/src/plugin/index.ts +1202 -0
  294. package/src/plugin/protocols.ts +404 -0
  295. package/src/plugin/schemas.ts +909 -0
  296. package/src/postgres/adapter.ts +904 -0
  297. package/src/postgres/index.ts +59 -0
  298. package/src/postgres/schema.sql +683 -0
  299. package/src/postgres/serializers.ts +485 -0
  300. package/src/postgres/sync.ts +254 -0
  301. package/src/postgres/types.ts +245 -0
  302. package/src/registries/builder.ts +607 -0
  303. package/src/registries/discovery.ts +572 -0
  304. package/src/registries/index.ts +77 -0
  305. package/src/registries/session.ts +613 -0
  306. package/src/registries/x402.ts +906 -0
  307. package/src/types/accounts.ts +618 -0
  308. package/src/types/common.ts +187 -0
  309. package/src/types/enums.ts +214 -0
  310. package/src/types/index.ts +92 -0
  311. package/src/types/instructions.ts +413 -0
  312. package/src/utils/hash.ts +57 -0
  313. package/src/utils/index.ts +19 -0
  314. package/src/utils/serialization.ts +98 -0
  315. package/src/utils/validation.ts +36 -0
@@ -0,0 +1,315 @@
1
+ /**
2
+ * @module tools
3
+ * @description Tool schema registry and session checkpoints for the
4
+ * Solana Agent Protocol.
5
+ *
6
+ * Covers: publish, inscribe schema, update, deactivate/reactivate,
7
+ * close, report invocations, and session checkpoint management.
8
+ *
9
+ * @category Modules
10
+ * @since v0.1.0
11
+ * @packageDocumentation
12
+ */
13
+ import { SystemProgram } from "@solana/web3.js";
14
+ import { BaseModule } from "./base";
15
+ import { deriveAgent, deriveTool, deriveCheckpoint, deriveGlobalRegistry, } from "../pda";
16
+ import { sha256, hashToArray } from "../utils";
17
+ /**
18
+ * @name ToolsModule
19
+ * @description Manages tool descriptors and session checkpoints for the
20
+ * Solana Agent Protocol. Provides methods to publish, update, deactivate,
21
+ * reactivate, close, and fetch tool descriptors, as well as inscribe
22
+ * JSON schemas into TX logs and manage session checkpoints.
23
+ *
24
+ * @category Modules
25
+ * @since v0.1.0
26
+ * @extends BaseModule
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * const sap = new SapClient(provider);
31
+ * // Publish a tool by name (auto-hashes)
32
+ * const sig = await sap.tools.publishByName(
33
+ * "getWeather", "mcp-v1", "Fetch weather",
34
+ * '{"type":"object"}', '{"type":"object"}',
35
+ * 0, 1, 2, 1, false,
36
+ * );
37
+ * ```
38
+ */
39
+ export class ToolsModule extends BaseModule {
40
+ // ── PDA helpers ──────────────────────────────────────
41
+ /**
42
+ * @name deriveTool
43
+ * @description Derive the `ToolDescriptor` PDA for a given agent and tool name.
44
+ * The tool name is SHA-256 hashed internally.
45
+ * @param agentPda - The agent account PDA.
46
+ * @param toolName - The human-readable tool name.
47
+ * @returns A tuple of `[PublicKey, bump]` for the tool PDA.
48
+ * @see {@link deriveTool} from `pda/` module for the underlying derivation.
49
+ * @since v0.1.0
50
+ */
51
+ deriveTool(agentPda, toolName) {
52
+ return deriveTool(agentPda, sha256(toolName));
53
+ }
54
+ // ── Instructions ─────────────────────────────────────
55
+ /**
56
+ * @name publish
57
+ * @description Publish a new tool descriptor for an agent using pre-computed
58
+ * hashes. For auto-hashing, prefer {@link publishByName}.
59
+ * @param args - Tool publication parameters (name, hashes, HTTP method, category, params, etc.).
60
+ * @returns {Promise<TransactionSignature>} The transaction signature.
61
+ * @since v0.1.0
62
+ */
63
+ async publish(args) {
64
+ const [agentPda] = deriveAgent(this.walletPubkey);
65
+ const [toolPda] = deriveTool(agentPda, new Uint8Array(args.toolNameHash));
66
+ const [globalPda] = deriveGlobalRegistry();
67
+ return this.methods
68
+ .publishTool(args.toolName, args.toolNameHash, args.protocolHash, args.descriptionHash, args.inputSchemaHash, args.outputSchemaHash, args.httpMethod, args.category, args.paramsCount, args.requiredParams, args.isCompound)
69
+ .accounts({
70
+ wallet: this.walletPubkey,
71
+ agent: agentPda,
72
+ tool: toolPda,
73
+ globalRegistry: globalPda,
74
+ systemProgram: SystemProgram.programId,
75
+ })
76
+ .rpc();
77
+ }
78
+ /**
79
+ * @name publishByName
80
+ * @description Convenience method to publish a tool using string names.
81
+ * All string arguments are automatically SHA-256 hashed.
82
+ * @param toolName - Human-readable tool name.
83
+ * @param protocolId - Protocol identifier (e.g. `"mcp-v1"`).
84
+ * @param description - Tool description text.
85
+ * @param inputSchema - JSON schema string for input validation.
86
+ * @param outputSchema - JSON schema string for output validation.
87
+ * @param httpMethod - Numeric HTTP method enum value.
88
+ * @param category - Numeric tool category enum value.
89
+ * @param paramsCount - Total number of parameters.
90
+ * @param requiredParams - Number of required parameters.
91
+ * @param isCompound - Whether the tool is a compound (multi-step) tool.
92
+ * @returns {Promise<TransactionSignature>} The transaction signature.
93
+ * @since v0.1.0
94
+ */
95
+ async publishByName(toolName, protocolId, description, inputSchema, outputSchema, httpMethod, category, paramsCount, requiredParams, isCompound) {
96
+ return this.publish({
97
+ toolName,
98
+ toolNameHash: hashToArray(sha256(toolName)),
99
+ protocolHash: hashToArray(sha256(protocolId)),
100
+ descriptionHash: hashToArray(sha256(description)),
101
+ inputSchemaHash: hashToArray(sha256(inputSchema)),
102
+ outputSchemaHash: hashToArray(sha256(outputSchema)),
103
+ httpMethod,
104
+ category,
105
+ paramsCount,
106
+ requiredParams,
107
+ isCompound,
108
+ });
109
+ }
110
+ /**
111
+ * @name inscribeSchema
112
+ * @description Inscribe a full JSON schema into the transaction log (zero rent).
113
+ * The schema is stored as TX log data, not as PDA account data.
114
+ * @param toolName - The human-readable tool name.
115
+ * @param args - Schema inscription parameters (type, data, hash, compression).
116
+ * @returns {Promise<TransactionSignature>} The transaction signature.
117
+ * @since v0.1.0
118
+ */
119
+ async inscribeSchema(toolName, args) {
120
+ const [agentPda] = deriveAgent(this.walletPubkey);
121
+ const [toolPda] = this.deriveTool(agentPda, toolName);
122
+ return this.methods
123
+ .inscribeToolSchema(args.schemaType, args.schemaData, args.schemaHash, args.compression)
124
+ .accounts({
125
+ wallet: this.walletPubkey,
126
+ agent: agentPda,
127
+ tool: toolPda,
128
+ })
129
+ .rpc();
130
+ }
131
+ /**
132
+ * @name update
133
+ * @description Update a tool’s schema hashes and bump its version.
134
+ * All fields are optional — only non-null values are written.
135
+ * @param toolName - The human-readable tool name.
136
+ * @param args - Partial update parameters (hashes, method, category, params).
137
+ * @returns {Promise<TransactionSignature>} The transaction signature.
138
+ * @since v0.1.0
139
+ */
140
+ async update(toolName, args) {
141
+ const [agentPda] = deriveAgent(this.walletPubkey);
142
+ const [toolPda] = this.deriveTool(agentPda, toolName);
143
+ return this.methods
144
+ .updateTool(args.descriptionHash ?? null, args.inputSchemaHash ?? null, args.outputSchemaHash ?? null, args.httpMethod ?? null, args.category ?? null, args.paramsCount ?? null, args.requiredParams ?? null)
145
+ .accounts({
146
+ wallet: this.walletPubkey,
147
+ agent: agentPda,
148
+ tool: toolPda,
149
+ })
150
+ .rpc();
151
+ }
152
+ /**
153
+ * @name deactivate
154
+ * @description Deactivate a tool. The tool remains discoverable but is
155
+ * marked as unavailable.
156
+ * @param toolName - The human-readable tool name.
157
+ * @returns {Promise<TransactionSignature>} The transaction signature.
158
+ * @since v0.1.0
159
+ */
160
+ async deactivate(toolName) {
161
+ const [agentPda] = deriveAgent(this.walletPubkey);
162
+ const [toolPda] = this.deriveTool(agentPda, toolName);
163
+ return this.methods
164
+ .deactivateTool()
165
+ .accounts({
166
+ wallet: this.walletPubkey,
167
+ agent: agentPda,
168
+ tool: toolPda,
169
+ })
170
+ .rpc();
171
+ }
172
+ /**
173
+ * @name reactivate
174
+ * @description Reactivate a previously deactivated tool.
175
+ * @param toolName - The human-readable tool name.
176
+ * @returns {Promise<TransactionSignature>} The transaction signature.
177
+ * @since v0.1.0
178
+ */
179
+ async reactivate(toolName) {
180
+ const [agentPda] = deriveAgent(this.walletPubkey);
181
+ const [toolPda] = this.deriveTool(agentPda, toolName);
182
+ return this.methods
183
+ .reactivateTool()
184
+ .accounts({
185
+ wallet: this.walletPubkey,
186
+ agent: agentPda,
187
+ tool: toolPda,
188
+ })
189
+ .rpc();
190
+ }
191
+ /**
192
+ * @name close
193
+ * @description Close a tool PDA and reclaim rent to the owner wallet.
194
+ * @param toolName - The human-readable tool name.
195
+ * @returns {Promise<TransactionSignature>} The transaction signature.
196
+ * @since v0.1.0
197
+ */
198
+ async close(toolName) {
199
+ const [agentPda] = deriveAgent(this.walletPubkey);
200
+ const [toolPda] = this.deriveTool(agentPda, toolName);
201
+ const [globalPda] = deriveGlobalRegistry();
202
+ return this.methods
203
+ .closeTool()
204
+ .accounts({
205
+ wallet: this.walletPubkey,
206
+ agent: agentPda,
207
+ tool: toolPda,
208
+ globalRegistry: globalPda,
209
+ })
210
+ .rpc();
211
+ }
212
+ /**
213
+ * @name reportInvocations
214
+ * @description Report tool invocation count. Updates the on-chain counter
215
+ * for analytics and discovery ranking.
216
+ * @param toolName - The human-readable tool name.
217
+ * @param invocations - The number of invocations to report.
218
+ * @returns {Promise<TransactionSignature>} The transaction signature.
219
+ * @since v0.1.0
220
+ */
221
+ async reportInvocations(toolName, invocations) {
222
+ const [agentPda] = deriveAgent(this.walletPubkey);
223
+ const [toolPda] = this.deriveTool(agentPda, toolName);
224
+ return this.methods
225
+ .reportToolInvocations(this.bn(invocations))
226
+ .accounts({
227
+ wallet: this.walletPubkey,
228
+ agent: agentPda,
229
+ tool: toolPda,
230
+ })
231
+ .rpc();
232
+ }
233
+ // ── Checkpoints ──────────────────────────────────────
234
+ /**
235
+ * @name createCheckpoint
236
+ * @description Create a checkpoint snapshot of the current session state.
237
+ * Checkpoints are indexed by session PDA and checkpoint index.
238
+ * @param sessionPda - The session ledger PDA.
239
+ * @param checkpointIndex - The zero-based checkpoint index.
240
+ * @returns {Promise<TransactionSignature>} The transaction signature.
241
+ * @since v0.1.0
242
+ */
243
+ async createCheckpoint(sessionPda, checkpointIndex) {
244
+ const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
245
+ return this.methods
246
+ .createSessionCheckpoint(checkpointIndex)
247
+ .accounts({
248
+ wallet: this.walletPubkey,
249
+ session: sessionPda,
250
+ checkpoint: checkpointPda,
251
+ systemProgram: SystemProgram.programId,
252
+ })
253
+ .rpc();
254
+ }
255
+ /**
256
+ * @name closeCheckpoint
257
+ * @description Close a checkpoint PDA and reclaim rent.
258
+ * @param sessionPda - The session ledger PDA.
259
+ * @param checkpointIndex - The zero-based checkpoint index.
260
+ * @returns {Promise<TransactionSignature>} The transaction signature.
261
+ * @since v0.1.0
262
+ */
263
+ async closeCheckpoint(sessionPda, checkpointIndex) {
264
+ const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
265
+ return this.methods
266
+ .closeCheckpoint(checkpointIndex)
267
+ .accounts({
268
+ wallet: this.walletPubkey,
269
+ session: sessionPda,
270
+ checkpoint: checkpointPda,
271
+ })
272
+ .rpc();
273
+ }
274
+ // ── Fetchers ─────────────────────────────────────────
275
+ /**
276
+ * @name fetch
277
+ * @description Fetch a deserialized `ToolDescriptor` account.
278
+ * @param agentPda - The agent account PDA.
279
+ * @param toolName - The human-readable tool name.
280
+ * @returns {Promise<ToolDescriptorData>} The tool descriptor data.
281
+ * @throws Will throw if the tool descriptor does not exist.
282
+ * @since v0.1.0
283
+ */
284
+ async fetch(agentPda, toolName) {
285
+ const [pda] = this.deriveTool(agentPda, toolName);
286
+ return this.fetchAccount("toolDescriptor", pda);
287
+ }
288
+ /**
289
+ * @name fetchNullable
290
+ * @description Fetch a deserialized `ToolDescriptor` account, or `null`
291
+ * if it does not exist on-chain.
292
+ * @param agentPda - The agent account PDA.
293
+ * @param toolName - The human-readable tool name.
294
+ * @returns {Promise<ToolDescriptorData | null>} The tool data or `null`.
295
+ * @since v0.1.0
296
+ */
297
+ async fetchNullable(agentPda, toolName) {
298
+ const [pda] = this.deriveTool(agentPda, toolName);
299
+ return this.fetchAccountNullable("toolDescriptor", pda);
300
+ }
301
+ /**
302
+ * @name fetchCheckpoint
303
+ * @description Fetch a deserialized `SessionCheckpoint` account by session PDA and index.
304
+ * @param sessionPda - The session ledger PDA.
305
+ * @param checkpointIndex - The zero-based checkpoint index.
306
+ * @returns {Promise<SessionCheckpointData>} The checkpoint data.
307
+ * @throws Will throw if the checkpoint does not exist.
308
+ * @since v0.1.0
309
+ */
310
+ async fetchCheckpoint(sessionPda, checkpointIndex) {
311
+ const [pda] = deriveCheckpoint(sessionPda, checkpointIndex);
312
+ return this.fetchAccount("sessionCheckpoint", pda);
313
+ }
314
+ }
315
+ //# sourceMappingURL=tools.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/modules/tools.ts"],"names":[],"mappings":"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"}