@aexol/spectral 0.8.2 → 0.8.5

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 (523) hide show
  1. package/CHANGELOG.md +82 -55
  2. package/README.md +80 -82
  3. package/dist/agent/agents.d.ts +37 -0
  4. package/dist/agent/agents.d.ts.map +1 -0
  5. package/dist/agent/index.d.ts +29 -0
  6. package/dist/agent/index.d.ts.map +1 -0
  7. package/dist/cli.d.ts +17 -0
  8. package/dist/cli.d.ts.map +1 -0
  9. package/dist/commands/bind.d.ts +12 -0
  10. package/dist/commands/bind.d.ts.map +1 -0
  11. package/dist/commands/login-oauth.d.ts +15 -0
  12. package/dist/commands/login-oauth.d.ts.map +1 -0
  13. package/dist/commands/login.d.ts +37 -0
  14. package/dist/commands/login.d.ts.map +1 -0
  15. package/dist/commands/logout.d.ts +8 -0
  16. package/dist/commands/logout.d.ts.map +1 -0
  17. package/dist/commands/serve.d.ts +112 -0
  18. package/dist/commands/serve.d.ts.map +1 -0
  19. package/dist/commands/unbind.d.ts +8 -0
  20. package/dist/commands/unbind.d.ts.map +1 -0
  21. package/dist/config.d.ts +49 -0
  22. package/dist/config.d.ts.map +1 -0
  23. package/dist/designer/guidelines.d.ts +23 -0
  24. package/dist/designer/guidelines.d.ts.map +1 -0
  25. package/dist/designer/index.d.ts +26 -0
  26. package/dist/designer/index.d.ts.map +1 -0
  27. package/dist/designer/philosophies.d.ts +33 -0
  28. package/dist/designer/philosophies.d.ts.map +1 -0
  29. package/dist/designer/skills.d.ts +27 -0
  30. package/dist/designer/skills.d.ts.map +1 -0
  31. package/dist/designer/systems.d.ts +36 -0
  32. package/dist/designer/systems.d.ts.map +1 -0
  33. package/dist/extensions/aexol-mcp.d.ts +25 -0
  34. package/dist/extensions/aexol-mcp.d.ts.map +1 -0
  35. package/dist/extensions/kanban-bridge.d.ts +24 -0
  36. package/dist/extensions/kanban-bridge.d.ts.map +1 -0
  37. package/dist/extensions/openrouter-attribution.d.ts +12 -0
  38. package/dist/extensions/openrouter-attribution.d.ts.map +1 -0
  39. package/dist/extensions/spectral-vision-fallback.d.ts +23 -0
  40. package/dist/extensions/spectral-vision-fallback.d.ts.map +1 -0
  41. package/dist/extensions/spectral-vision-fallback.js +29 -20
  42. package/dist/index.d.ts +46 -0
  43. package/dist/index.d.ts.map +1 -0
  44. package/dist/index.js +44 -0
  45. package/dist/mcp/agent-dir.d.ts +3 -0
  46. package/dist/mcp/agent-dir.d.ts.map +1 -0
  47. package/dist/mcp/commands.d.ts +9 -0
  48. package/dist/mcp/commands.d.ts.map +1 -0
  49. package/dist/mcp/config.d.ts +78 -0
  50. package/dist/mcp/config.d.ts.map +1 -0
  51. package/dist/mcp/consent-manager.d.ts +14 -0
  52. package/dist/mcp/consent-manager.d.ts.map +1 -0
  53. package/dist/mcp/direct-tools.d.ts +11 -0
  54. package/dist/mcp/direct-tools.d.ts.map +1 -0
  55. package/dist/mcp/errors.d.ts +100 -0
  56. package/dist/mcp/errors.d.ts.map +1 -0
  57. package/dist/mcp/glimpse-ui.d.ts +10 -0
  58. package/dist/mcp/glimpse-ui.d.ts.map +1 -0
  59. package/dist/mcp/host-html-template.d.ts +17 -0
  60. package/dist/mcp/host-html-template.d.ts.map +1 -0
  61. package/dist/mcp/index.d.ts +3 -0
  62. package/dist/mcp/index.d.ts.map +1 -0
  63. package/dist/mcp/init.d.ts +10 -0
  64. package/dist/mcp/init.d.ts.map +1 -0
  65. package/dist/mcp/lifecycle.d.ts +30 -0
  66. package/dist/mcp/lifecycle.d.ts.map +1 -0
  67. package/dist/mcp/logger.d.ts +52 -0
  68. package/dist/mcp/logger.d.ts.map +1 -0
  69. package/dist/mcp/mcp-auth-flow.d.ts +69 -0
  70. package/dist/mcp/mcp-auth-flow.d.ts.map +1 -0
  71. package/dist/mcp/mcp-auth.d.ts +100 -0
  72. package/dist/mcp/mcp-auth.d.ts.map +1 -0
  73. package/dist/mcp/mcp-callback-server.d.ts +40 -0
  74. package/dist/mcp/mcp-callback-server.d.ts.map +1 -0
  75. package/dist/mcp/mcp-oauth-provider.d.ts +101 -0
  76. package/dist/mcp/mcp-oauth-provider.d.ts.map +1 -0
  77. package/dist/mcp/metadata-cache.d.ts +32 -0
  78. package/dist/mcp/metadata-cache.d.ts.map +1 -0
  79. package/dist/mcp/npx-resolver.d.ts +7 -0
  80. package/dist/mcp/npx-resolver.d.ts.map +1 -0
  81. package/dist/mcp/oauth-handler.d.ts +19 -0
  82. package/dist/mcp/oauth-handler.d.ts.map +1 -0
  83. package/dist/mcp/onboarding-state.d.ts +13 -0
  84. package/dist/mcp/onboarding-state.d.ts.map +1 -0
  85. package/dist/mcp/proxy-modes.d.ts +12 -0
  86. package/dist/mcp/proxy-modes.d.ts.map +1 -0
  87. package/dist/mcp/resource-tools.d.ts +2 -0
  88. package/dist/mcp/resource-tools.d.ts.map +1 -0
  89. package/dist/mcp/sampling-handler.d.ts +16 -0
  90. package/dist/mcp/sampling-handler.d.ts.map +1 -0
  91. package/dist/mcp/server-manager.d.ts +42 -0
  92. package/dist/mcp/server-manager.d.ts.map +1 -0
  93. package/dist/mcp/state.d.ts +41 -0
  94. package/dist/mcp/state.d.ts.map +1 -0
  95. package/dist/mcp/tool-metadata.d.ts +11 -0
  96. package/dist/mcp/tool-metadata.d.ts.map +1 -0
  97. package/dist/mcp/tool-registrar.d.ts +9 -0
  98. package/dist/mcp/tool-registrar.d.ts.map +1 -0
  99. package/dist/mcp/types.d.ts +263 -0
  100. package/dist/mcp/types.d.ts.map +1 -0
  101. package/dist/mcp/ui-resource-handler.d.ts +10 -0
  102. package/dist/mcp/ui-resource-handler.d.ts.map +1 -0
  103. package/dist/mcp/ui-server.d.ts +37 -0
  104. package/dist/mcp/ui-server.d.ts.map +1 -0
  105. package/dist/mcp/ui-session.d.ts +27 -0
  106. package/dist/mcp/ui-session.d.ts.map +1 -0
  107. package/dist/mcp/ui-stream-types.d.ts +197 -0
  108. package/dist/mcp/ui-stream-types.d.ts.map +1 -0
  109. package/dist/mcp/utils.d.ts +17 -0
  110. package/dist/mcp/utils.d.ts.map +1 -0
  111. package/dist/mcp/vitest.config.d.ts +3 -0
  112. package/dist/mcp/vitest.config.d.ts.map +1 -0
  113. package/dist/mcp-client.d.ts +58 -0
  114. package/dist/mcp-client.d.ts.map +1 -0
  115. package/dist/mcp-client.js +2 -1
  116. package/dist/memory/branch.d.ts +124 -0
  117. package/dist/memory/branch.d.ts.map +1 -0
  118. package/dist/memory/commands/status.d.ts +4 -0
  119. package/dist/memory/commands/status.d.ts.map +1 -0
  120. package/dist/memory/commands/view.d.ts +4 -0
  121. package/dist/memory/commands/view.d.ts.map +1 -0
  122. package/dist/memory/compaction.d.ts +113 -0
  123. package/dist/memory/compaction.d.ts.map +1 -0
  124. package/dist/memory/config.d.ts +27 -0
  125. package/dist/memory/config.d.ts.map +1 -0
  126. package/dist/memory/debug-log.d.ts +12 -0
  127. package/dist/memory/debug-log.d.ts.map +1 -0
  128. package/dist/memory/hooks/compaction-hook.d.ts +4 -0
  129. package/dist/memory/hooks/compaction-hook.d.ts.map +1 -0
  130. package/dist/memory/hooks/compaction-trigger.d.ts +4 -0
  131. package/dist/memory/hooks/compaction-trigger.d.ts.map +1 -0
  132. package/dist/memory/hooks/observer-trigger.d.ts +4 -0
  133. package/dist/memory/hooks/observer-trigger.d.ts.map +1 -0
  134. package/dist/memory/ids.d.ts +2 -0
  135. package/dist/memory/ids.d.ts.map +1 -0
  136. package/dist/memory/index.d.ts +3 -0
  137. package/dist/memory/index.d.ts.map +1 -0
  138. package/dist/memory/model-budget.d.ts +4 -0
  139. package/dist/memory/model-budget.d.ts.map +1 -0
  140. package/dist/memory/observer.d.ts +21 -0
  141. package/dist/memory/observer.d.ts.map +1 -0
  142. package/dist/memory/project-observations-store.d.ts +24 -0
  143. package/dist/memory/project-observations-store.d.ts.map +1 -0
  144. package/dist/memory/prompts.d.ts +11 -0
  145. package/dist/memory/prompts.d.ts.map +1 -0
  146. package/dist/memory/relevance.d.ts +4 -0
  147. package/dist/memory/relevance.d.ts.map +1 -0
  148. package/dist/memory/runtime.d.ts +40 -0
  149. package/dist/memory/runtime.d.ts.map +1 -0
  150. package/dist/memory/serialize.d.ts +26 -0
  151. package/dist/memory/serialize.d.ts.map +1 -0
  152. package/dist/memory/tokens.d.ts +8 -0
  153. package/dist/memory/tokens.d.ts.map +1 -0
  154. package/dist/memory/tools/read-project-observations.d.ts +8 -0
  155. package/dist/memory/tools/read-project-observations.d.ts.map +1 -0
  156. package/dist/memory/tools/recall-observation.d.ts +63 -0
  157. package/dist/memory/tools/recall-observation.d.ts.map +1 -0
  158. package/dist/memory/tools/write-project-observation.d.ts +9 -0
  159. package/dist/memory/tools/write-project-observation.d.ts.map +1 -0
  160. package/dist/memory/types.d.ts +65 -0
  161. package/dist/memory/types.d.ts.map +1 -0
  162. package/dist/preflight.d.ts +27 -0
  163. package/dist/preflight.d.ts.map +1 -0
  164. package/dist/preflight.js +3 -1
  165. package/dist/relay/auto-research.d.ts +64 -0
  166. package/dist/relay/auto-research.d.ts.map +1 -0
  167. package/dist/relay/auto-research.js +174 -69
  168. package/dist/relay/client.d.ts +126 -0
  169. package/dist/relay/client.d.ts.map +1 -0
  170. package/dist/relay/dispatcher.d.ts +207 -0
  171. package/dist/relay/dispatcher.d.ts.map +1 -0
  172. package/dist/relay/machine-store.d.ts +68 -0
  173. package/dist/relay/machine-store.d.ts.map +1 -0
  174. package/dist/relay/models-fetch.d.ts +75 -0
  175. package/dist/relay/models-fetch.d.ts.map +1 -0
  176. package/dist/relay/registration.d.ts +81 -0
  177. package/dist/relay/registration.d.ts.map +1 -0
  178. package/dist/sdk/agent-core/agent-loop.d.ts +24 -0
  179. package/dist/sdk/agent-core/agent-loop.d.ts.map +1 -0
  180. package/dist/sdk/agent-core/agent.d.ts +125 -0
  181. package/dist/sdk/agent-core/agent.d.ts.map +1 -0
  182. package/dist/sdk/agent-core/harness/agent-harness.d.ts +92 -0
  183. package/dist/sdk/agent-core/harness/agent-harness.d.ts.map +1 -0
  184. package/dist/sdk/agent-core/harness/compaction/branch-summarization.d.ts +53 -0
  185. package/dist/sdk/agent-core/harness/compaction/branch-summarization.d.ts.map +1 -0
  186. package/dist/sdk/agent-core/harness/compaction/compaction.d.ts +95 -0
  187. package/dist/sdk/agent-core/harness/compaction/compaction.d.ts.map +1 -0
  188. package/dist/sdk/agent-core/harness/compaction/utils.d.ts +25 -0
  189. package/dist/sdk/agent-core/harness/compaction/utils.d.ts.map +1 -0
  190. package/dist/sdk/agent-core/harness/env/nodejs.d.ts +51 -0
  191. package/dist/sdk/agent-core/harness/env/nodejs.d.ts.map +1 -0
  192. package/dist/sdk/agent-core/harness/messages.d.ts +51 -0
  193. package/dist/sdk/agent-core/harness/messages.d.ts.map +1 -0
  194. package/dist/sdk/agent-core/harness/prompt-templates.d.ts +48 -0
  195. package/dist/sdk/agent-core/harness/prompt-templates.d.ts.map +1 -0
  196. package/dist/sdk/agent-core/harness/session/jsonl-repo.d.ts +26 -0
  197. package/dist/sdk/agent-core/harness/session/jsonl-repo.d.ts.map +1 -0
  198. package/dist/sdk/agent-core/harness/session/jsonl-storage.d.ts +33 -0
  199. package/dist/sdk/agent-core/harness/session/jsonl-storage.d.ts.map +1 -0
  200. package/dist/sdk/agent-core/harness/session/memory-repo.d.ts +18 -0
  201. package/dist/sdk/agent-core/harness/session/memory-repo.d.ts.map +1 -0
  202. package/dist/sdk/agent-core/harness/session/memory-storage.d.ts +25 -0
  203. package/dist/sdk/agent-core/harness/session/memory-storage.d.ts.map +1 -0
  204. package/dist/sdk/agent-core/harness/session/repo-utils.d.ts +11 -0
  205. package/dist/sdk/agent-core/harness/session/repo-utils.d.ts.map +1 -0
  206. package/dist/sdk/agent-core/harness/session/session.d.ts +32 -0
  207. package/dist/sdk/agent-core/harness/session/session.d.ts.map +1 -0
  208. package/dist/sdk/agent-core/harness/session/uuid.d.ts +2 -0
  209. package/dist/sdk/agent-core/harness/session/uuid.d.ts.map +1 -0
  210. package/dist/sdk/agent-core/harness/skills.d.ts +44 -0
  211. package/dist/sdk/agent-core/harness/skills.d.ts.map +1 -0
  212. package/dist/sdk/agent-core/harness/system-prompt.d.ts +3 -0
  213. package/dist/sdk/agent-core/harness/system-prompt.d.ts.map +1 -0
  214. package/dist/sdk/agent-core/harness/types.d.ts +601 -0
  215. package/dist/sdk/agent-core/harness/types.d.ts.map +1 -0
  216. package/dist/sdk/agent-core/harness/utils/shell-output.d.ts +14 -0
  217. package/dist/sdk/agent-core/harness/utils/shell-output.d.ts.map +1 -0
  218. package/dist/sdk/agent-core/harness/utils/truncate.d.ts +70 -0
  219. package/dist/sdk/agent-core/harness/utils/truncate.d.ts.map +1 -0
  220. package/dist/sdk/agent-core/index.d.ts +20 -0
  221. package/dist/sdk/agent-core/index.d.ts.map +1 -0
  222. package/dist/sdk/agent-core/node.d.ts +3 -0
  223. package/dist/sdk/agent-core/node.d.ts.map +1 -0
  224. package/dist/sdk/agent-core/proxy.d.ts +69 -0
  225. package/dist/sdk/agent-core/proxy.d.ts.map +1 -0
  226. package/dist/sdk/agent-core/types.d.ts +393 -0
  227. package/dist/sdk/agent-core/types.d.ts.map +1 -0
  228. package/dist/sdk/ai/api-registry.d.ts +20 -0
  229. package/dist/sdk/ai/api-registry.d.ts.map +1 -0
  230. package/dist/sdk/ai/cli.d.ts +3 -0
  231. package/dist/sdk/ai/cli.d.ts.map +1 -0
  232. package/dist/sdk/ai/env-api-keys.d.ts +18 -0
  233. package/dist/sdk/ai/env-api-keys.d.ts.map +1 -0
  234. package/dist/sdk/ai/image-models.d.ts +10 -0
  235. package/dist/sdk/ai/image-models.d.ts.map +1 -0
  236. package/dist/sdk/ai/image-models.generated.d.ts +440 -0
  237. package/dist/sdk/ai/image-models.generated.d.ts.map +1 -0
  238. package/dist/sdk/ai/images-api-registry.d.ts +14 -0
  239. package/dist/sdk/ai/images-api-registry.d.ts.map +1 -0
  240. package/dist/sdk/ai/images.d.ts +4 -0
  241. package/dist/sdk/ai/images.d.ts.map +1 -0
  242. package/dist/sdk/ai/index.d.ts +21 -0
  243. package/dist/sdk/ai/index.d.ts.map +1 -0
  244. package/dist/sdk/ai/models.d.ts +18 -0
  245. package/dist/sdk/ai/models.d.ts.map +1 -0
  246. package/dist/sdk/ai/models.generated.d.ts +17349 -0
  247. package/dist/sdk/ai/models.generated.d.ts.map +1 -0
  248. package/dist/sdk/ai/oauth.d.ts +2 -0
  249. package/dist/sdk/ai/oauth.d.ts.map +1 -0
  250. package/dist/sdk/ai/providers/anthropic.d.ts +54 -0
  251. package/dist/sdk/ai/providers/anthropic.d.ts.map +1 -0
  252. package/dist/sdk/ai/providers/faux.d.ts +56 -0
  253. package/dist/sdk/ai/providers/faux.d.ts.map +1 -0
  254. package/dist/sdk/ai/providers/github-copilot-headers.d.ts +8 -0
  255. package/dist/sdk/ai/providers/github-copilot-headers.d.ts.map +1 -0
  256. package/dist/sdk/ai/providers/openai-completions.d.ts +19 -0
  257. package/dist/sdk/ai/providers/openai-completions.d.ts.map +1 -0
  258. package/dist/sdk/ai/providers/openai-prompt-cache.d.ts +3 -0
  259. package/dist/sdk/ai/providers/openai-prompt-cache.d.ts.map +1 -0
  260. package/dist/sdk/ai/providers/register-builtins.d.ts +15 -0
  261. package/dist/sdk/ai/providers/register-builtins.d.ts.map +1 -0
  262. package/dist/sdk/ai/providers/simple-options.d.ts +8 -0
  263. package/dist/sdk/ai/providers/simple-options.d.ts.map +1 -0
  264. package/dist/sdk/ai/providers/transform-messages.d.ts +8 -0
  265. package/dist/sdk/ai/providers/transform-messages.d.ts.map +1 -0
  266. package/dist/sdk/ai/session-resources.d.ts +4 -0
  267. package/dist/sdk/ai/session-resources.d.ts.map +1 -0
  268. package/dist/sdk/ai/stream.d.ts +8 -0
  269. package/dist/sdk/ai/stream.d.ts.map +1 -0
  270. package/dist/sdk/ai/types.d.ts +488 -0
  271. package/dist/sdk/ai/types.d.ts.map +1 -0
  272. package/dist/sdk/ai/utils/diagnostics.d.ts +19 -0
  273. package/dist/sdk/ai/utils/diagnostics.d.ts.map +1 -0
  274. package/dist/sdk/ai/utils/event-stream.d.ts +21 -0
  275. package/dist/sdk/ai/utils/event-stream.d.ts.map +1 -0
  276. package/dist/sdk/ai/utils/hash.d.ts +3 -0
  277. package/dist/sdk/ai/utils/hash.d.ts.map +1 -0
  278. package/dist/sdk/ai/utils/headers.d.ts +2 -0
  279. package/dist/sdk/ai/utils/headers.d.ts.map +1 -0
  280. package/dist/sdk/ai/utils/json-parse.d.ts +16 -0
  281. package/dist/sdk/ai/utils/json-parse.d.ts.map +1 -0
  282. package/dist/sdk/ai/utils/node-http-proxy.d.ts +10 -0
  283. package/dist/sdk/ai/utils/node-http-proxy.d.ts.map +1 -0
  284. package/dist/sdk/ai/utils/oauth/anthropic.d.ts +25 -0
  285. package/dist/sdk/ai/utils/oauth/anthropic.d.ts.map +1 -0
  286. package/dist/sdk/ai/utils/oauth/device-code.d.ts +19 -0
  287. package/dist/sdk/ai/utils/oauth/device-code.d.ts.map +1 -0
  288. package/dist/sdk/ai/utils/oauth/github-copilot.d.ts +30 -0
  289. package/dist/sdk/ai/utils/oauth/github-copilot.d.ts.map +1 -0
  290. package/dist/sdk/ai/utils/oauth/index.d.ts +58 -0
  291. package/dist/sdk/ai/utils/oauth/index.d.ts.map +1 -0
  292. package/dist/sdk/ai/utils/oauth/oauth-page.d.ts +3 -0
  293. package/dist/sdk/ai/utils/oauth/oauth-page.d.ts.map +1 -0
  294. package/dist/sdk/ai/utils/oauth/openai-codex.d.ts +34 -0
  295. package/dist/sdk/ai/utils/oauth/openai-codex.d.ts.map +1 -0
  296. package/dist/sdk/ai/utils/oauth/pkce.d.ts +13 -0
  297. package/dist/sdk/ai/utils/oauth/pkce.d.ts.map +1 -0
  298. package/dist/sdk/ai/utils/oauth/types.d.ts +64 -0
  299. package/dist/sdk/ai/utils/oauth/types.d.ts.map +1 -0
  300. package/dist/sdk/ai/utils/overflow.d.ts +56 -0
  301. package/dist/sdk/ai/utils/overflow.d.ts.map +1 -0
  302. package/dist/sdk/ai/utils/sanitize-unicode.d.ts +22 -0
  303. package/dist/sdk/ai/utils/sanitize-unicode.d.ts.map +1 -0
  304. package/dist/sdk/ai/utils/typebox-helpers.d.ts +17 -0
  305. package/dist/sdk/ai/utils/typebox-helpers.d.ts.map +1 -0
  306. package/dist/sdk/ai/utils/validation.d.ts +18 -0
  307. package/dist/sdk/ai/utils/validation.d.ts.map +1 -0
  308. package/dist/sdk/coding-agent/cli.d.ts +3 -0
  309. package/dist/sdk/coding-agent/cli.d.ts.map +1 -0
  310. package/dist/sdk/coding-agent/config.d.ts +71 -0
  311. package/dist/sdk/coding-agent/config.d.ts.map +1 -0
  312. package/dist/sdk/coding-agent/core/agent-session-runtime.d.ts +117 -0
  313. package/dist/sdk/coding-agent/core/agent-session-runtime.d.ts.map +1 -0
  314. package/dist/sdk/coding-agent/core/agent-session-services.d.ts +86 -0
  315. package/dist/sdk/coding-agent/core/agent-session-services.d.ts.map +1 -0
  316. package/dist/sdk/coding-agent/core/agent-session.d.ts +626 -0
  317. package/dist/sdk/coding-agent/core/agent-session.d.ts.map +1 -0
  318. package/dist/sdk/coding-agent/core/auth-guidance.d.ts +5 -0
  319. package/dist/sdk/coding-agent/core/auth-guidance.d.ts.map +1 -0
  320. package/dist/sdk/coding-agent/core/auth-storage.d.ts +145 -0
  321. package/dist/sdk/coding-agent/core/auth-storage.d.ts.map +1 -0
  322. package/dist/sdk/coding-agent/core/bash-executor.d.ts +32 -0
  323. package/dist/sdk/coding-agent/core/bash-executor.d.ts.map +1 -0
  324. package/dist/sdk/coding-agent/core/compaction/branch-summarization.d.ts +88 -0
  325. package/dist/sdk/coding-agent/core/compaction/branch-summarization.d.ts.map +1 -0
  326. package/dist/sdk/coding-agent/core/compaction/compaction.d.ts +142 -0
  327. package/dist/sdk/coding-agent/core/compaction/compaction.d.ts.map +1 -0
  328. package/dist/sdk/coding-agent/core/compaction/index.d.ts +7 -0
  329. package/dist/sdk/coding-agent/core/compaction/index.d.ts.map +1 -0
  330. package/dist/sdk/coding-agent/core/compaction/utils.d.ts +38 -0
  331. package/dist/sdk/coding-agent/core/compaction/utils.d.ts.map +1 -0
  332. package/dist/sdk/coding-agent/core/defaults.d.ts +3 -0
  333. package/dist/sdk/coding-agent/core/defaults.d.ts.map +1 -0
  334. package/dist/sdk/coding-agent/core/diagnostics.d.ts +15 -0
  335. package/dist/sdk/coding-agent/core/diagnostics.d.ts.map +1 -0
  336. package/dist/sdk/coding-agent/core/event-bus.d.ts +9 -0
  337. package/dist/sdk/coding-agent/core/event-bus.d.ts.map +1 -0
  338. package/dist/sdk/coding-agent/core/exec.d.ts +29 -0
  339. package/dist/sdk/coding-agent/core/exec.d.ts.map +1 -0
  340. package/dist/sdk/coding-agent/core/extensions/index.d.ts +12 -0
  341. package/dist/sdk/coding-agent/core/extensions/index.d.ts.map +1 -0
  342. package/dist/sdk/coding-agent/core/extensions/loader.d.ts +24 -0
  343. package/dist/sdk/coding-agent/core/extensions/loader.d.ts.map +1 -0
  344. package/dist/sdk/coding-agent/core/extensions/loader.js +1 -0
  345. package/dist/sdk/coding-agent/core/extensions/runner.d.ts +161 -0
  346. package/dist/sdk/coding-agent/core/extensions/runner.d.ts.map +1 -0
  347. package/dist/sdk/coding-agent/core/extensions/types.d.ts +1181 -0
  348. package/dist/sdk/coding-agent/core/extensions/types.d.ts.map +1 -0
  349. package/dist/sdk/coding-agent/core/extensions/wrapper.d.ts +20 -0
  350. package/dist/sdk/coding-agent/core/extensions/wrapper.d.ts.map +1 -0
  351. package/dist/sdk/coding-agent/core/http-dispatcher.d.ts +21 -0
  352. package/dist/sdk/coding-agent/core/http-dispatcher.d.ts.map +1 -0
  353. package/dist/sdk/coding-agent/core/index.d.ts +12 -0
  354. package/dist/sdk/coding-agent/core/index.d.ts.map +1 -0
  355. package/dist/sdk/coding-agent/core/keybindings.d.ts +371 -0
  356. package/dist/sdk/coding-agent/core/keybindings.d.ts.map +1 -0
  357. package/dist/sdk/coding-agent/core/messages.d.ts +77 -0
  358. package/dist/sdk/coding-agent/core/messages.d.ts.map +1 -0
  359. package/dist/sdk/coding-agent/core/model-registry.d.ts +150 -0
  360. package/dist/sdk/coding-agent/core/model-registry.d.ts.map +1 -0
  361. package/dist/sdk/coding-agent/core/model-resolver-utils.d.ts +7 -0
  362. package/dist/sdk/coding-agent/core/model-resolver-utils.d.ts.map +1 -0
  363. package/dist/sdk/coding-agent/core/model-resolver.d.ts +110 -0
  364. package/dist/sdk/coding-agent/core/model-resolver.d.ts.map +1 -0
  365. package/dist/sdk/coding-agent/core/output-guard.d.ts +6 -0
  366. package/dist/sdk/coding-agent/core/output-guard.d.ts.map +1 -0
  367. package/dist/sdk/coding-agent/core/package-manager.d.ts +204 -0
  368. package/dist/sdk/coding-agent/core/package-manager.d.ts.map +1 -0
  369. package/dist/sdk/coding-agent/core/prompt-templates.d.ts +52 -0
  370. package/dist/sdk/coding-agent/core/prompt-templates.d.ts.map +1 -0
  371. package/dist/sdk/coding-agent/core/provider-display-names.d.ts +2 -0
  372. package/dist/sdk/coding-agent/core/provider-display-names.d.ts.map +1 -0
  373. package/dist/sdk/coding-agent/core/resolve-config-value.d.ts +23 -0
  374. package/dist/sdk/coding-agent/core/resolve-config-value.d.ts.map +1 -0
  375. package/dist/sdk/coding-agent/core/resource-loader.d.ts +194 -0
  376. package/dist/sdk/coding-agent/core/resource-loader.d.ts.map +1 -0
  377. package/dist/sdk/coding-agent/core/sdk.d.ts +107 -0
  378. package/dist/sdk/coding-agent/core/sdk.d.ts.map +1 -0
  379. package/dist/sdk/coding-agent/core/session-cwd.d.ts +19 -0
  380. package/dist/sdk/coding-agent/core/session-cwd.d.ts.map +1 -0
  381. package/dist/sdk/coding-agent/core/session-manager.d.ts +333 -0
  382. package/dist/sdk/coding-agent/core/session-manager.d.ts.map +1 -0
  383. package/dist/sdk/coding-agent/core/settings-manager.d.ts +209 -0
  384. package/dist/sdk/coding-agent/core/settings-manager.d.ts.map +1 -0
  385. package/dist/sdk/coding-agent/core/skills.d.ts +60 -0
  386. package/dist/sdk/coding-agent/core/skills.d.ts.map +1 -0
  387. package/dist/sdk/coding-agent/core/slash-commands.d.ts +14 -0
  388. package/dist/sdk/coding-agent/core/slash-commands.d.ts.map +1 -0
  389. package/dist/sdk/coding-agent/core/source-info.d.ts +18 -0
  390. package/dist/sdk/coding-agent/core/source-info.d.ts.map +1 -0
  391. package/dist/sdk/coding-agent/core/system-prompt.d.ts +28 -0
  392. package/dist/sdk/coding-agent/core/system-prompt.d.ts.map +1 -0
  393. package/dist/sdk/coding-agent/core/telemetry.d.ts +3 -0
  394. package/dist/sdk/coding-agent/core/telemetry.d.ts.map +1 -0
  395. package/dist/sdk/coding-agent/core/theme.d.ts +28 -0
  396. package/dist/sdk/coding-agent/core/theme.d.ts.map +1 -0
  397. package/dist/sdk/coding-agent/core/timings.d.ts +8 -0
  398. package/dist/sdk/coding-agent/core/timings.d.ts.map +1 -0
  399. package/dist/sdk/coding-agent/core/tools/bash.d.ts +63 -0
  400. package/dist/sdk/coding-agent/core/tools/bash.d.ts.map +1 -0
  401. package/dist/sdk/coding-agent/core/tools/edit-diff.d.ts +87 -0
  402. package/dist/sdk/coding-agent/core/tools/edit-diff.d.ts.map +1 -0
  403. package/dist/sdk/coding-agent/core/tools/edit.d.ts +39 -0
  404. package/dist/sdk/coding-agent/core/tools/edit.d.ts.map +1 -0
  405. package/dist/sdk/coding-agent/core/tools/file-mutation-queue.d.ts +6 -0
  406. package/dist/sdk/coding-agent/core/tools/file-mutation-queue.d.ts.map +1 -0
  407. package/dist/sdk/coding-agent/core/tools/find.d.ts +35 -0
  408. package/dist/sdk/coding-agent/core/tools/find.d.ts.map +1 -0
  409. package/dist/sdk/coding-agent/core/tools/grep.d.ts +37 -0
  410. package/dist/sdk/coding-agent/core/tools/grep.d.ts.map +1 -0
  411. package/dist/sdk/coding-agent/core/tools/index.d.ts +40 -0
  412. package/dist/sdk/coding-agent/core/tools/index.d.ts.map +1 -0
  413. package/dist/sdk/coding-agent/core/tools/ls.d.ts +37 -0
  414. package/dist/sdk/coding-agent/core/tools/ls.d.ts.map +1 -0
  415. package/dist/sdk/coding-agent/core/tools/output-accumulator.d.ts +52 -0
  416. package/dist/sdk/coding-agent/core/tools/output-accumulator.d.ts.map +1 -0
  417. package/dist/sdk/coding-agent/core/tools/path-utils.d.ts +8 -0
  418. package/dist/sdk/coding-agent/core/tools/path-utils.d.ts.map +1 -0
  419. package/dist/sdk/coding-agent/core/tools/read.d.ts +35 -0
  420. package/dist/sdk/coding-agent/core/tools/read.d.ts.map +1 -0
  421. package/dist/sdk/coding-agent/core/tools/read.js +18 -10
  422. package/dist/sdk/coding-agent/core/tools/render-diff.d.ts +17 -0
  423. package/dist/sdk/coding-agent/core/tools/render-diff.d.ts.map +1 -0
  424. package/dist/sdk/coding-agent/core/tools/render-utils.d.ts +21 -0
  425. package/dist/sdk/coding-agent/core/tools/render-utils.d.ts.map +1 -0
  426. package/dist/sdk/coding-agent/core/tools/tool-definition-wrapper.d.ts +14 -0
  427. package/dist/sdk/coding-agent/core/tools/tool-definition-wrapper.d.ts.map +1 -0
  428. package/dist/sdk/coding-agent/core/tools/truncate.d.ts +70 -0
  429. package/dist/sdk/coding-agent/core/tools/truncate.d.ts.map +1 -0
  430. package/dist/sdk/coding-agent/core/tools/write.d.ts +26 -0
  431. package/dist/sdk/coding-agent/core/tools/write.d.ts.map +1 -0
  432. package/dist/sdk/coding-agent/index.d.ts +29 -0
  433. package/dist/sdk/coding-agent/index.d.ts.map +1 -0
  434. package/dist/sdk/coding-agent/main.d.ts +2 -0
  435. package/dist/sdk/coding-agent/main.d.ts.map +1 -0
  436. package/dist/sdk/coding-agent/migrations.d.ts +33 -0
  437. package/dist/sdk/coding-agent/migrations.d.ts.map +1 -0
  438. package/dist/sdk/coding-agent/modes/index.d.ts +8 -0
  439. package/dist/sdk/coding-agent/modes/index.d.ts.map +1 -0
  440. package/dist/sdk/coding-agent/modes/print-mode.d.ts +28 -0
  441. package/dist/sdk/coding-agent/modes/print-mode.d.ts.map +1 -0
  442. package/dist/sdk/coding-agent/modes/rpc/jsonl.d.ts +17 -0
  443. package/dist/sdk/coding-agent/modes/rpc/jsonl.d.ts.map +1 -0
  444. package/dist/sdk/coding-agent/modes/rpc/rpc-client.d.ts +224 -0
  445. package/dist/sdk/coding-agent/modes/rpc/rpc-client.d.ts.map +1 -0
  446. package/dist/sdk/coding-agent/modes/rpc/rpc-mode.d.ts +20 -0
  447. package/dist/sdk/coding-agent/modes/rpc/rpc-mode.d.ts.map +1 -0
  448. package/dist/sdk/coding-agent/modes/rpc/rpc-types.d.ts +419 -0
  449. package/dist/sdk/coding-agent/modes/rpc/rpc-types.d.ts.map +1 -0
  450. package/dist/sdk/coding-agent/utils/ansi.d.ts +2 -0
  451. package/dist/sdk/coding-agent/utils/ansi.d.ts.map +1 -0
  452. package/dist/sdk/coding-agent/utils/changelog.d.ts +21 -0
  453. package/dist/sdk/coding-agent/utils/changelog.d.ts.map +1 -0
  454. package/dist/sdk/coding-agent/utils/child-process.d.ts +15 -0
  455. package/dist/sdk/coding-agent/utils/child-process.d.ts.map +1 -0
  456. package/dist/sdk/coding-agent/utils/clipboard-image.d.ts +11 -0
  457. package/dist/sdk/coding-agent/utils/clipboard-image.d.ts.map +1 -0
  458. package/dist/sdk/coding-agent/utils/clipboard-native.d.ts +8 -0
  459. package/dist/sdk/coding-agent/utils/clipboard-native.d.ts.map +1 -0
  460. package/dist/sdk/coding-agent/utils/clipboard.d.ts +2 -0
  461. package/dist/sdk/coding-agent/utils/clipboard.d.ts.map +1 -0
  462. package/dist/sdk/coding-agent/utils/exif-orientation.d.ts +5 -0
  463. package/dist/sdk/coding-agent/utils/exif-orientation.d.ts.map +1 -0
  464. package/dist/sdk/coding-agent/utils/frontmatter.d.ts +8 -0
  465. package/dist/sdk/coding-agent/utils/frontmatter.d.ts.map +1 -0
  466. package/dist/sdk/coding-agent/utils/fs-watch.d.ts +5 -0
  467. package/dist/sdk/coding-agent/utils/fs-watch.d.ts.map +1 -0
  468. package/dist/sdk/coding-agent/utils/git.d.ts +26 -0
  469. package/dist/sdk/coding-agent/utils/git.d.ts.map +1 -0
  470. package/dist/sdk/coding-agent/utils/html.d.ts +7 -0
  471. package/dist/sdk/coding-agent/utils/html.d.ts.map +1 -0
  472. package/dist/sdk/coding-agent/utils/image-convert.d.ts +9 -0
  473. package/dist/sdk/coding-agent/utils/image-convert.d.ts.map +1 -0
  474. package/dist/sdk/coding-agent/utils/image-resize.d.ts +36 -0
  475. package/dist/sdk/coding-agent/utils/image-resize.d.ts.map +1 -0
  476. package/dist/sdk/coding-agent/utils/mime.d.ts +3 -0
  477. package/dist/sdk/coding-agent/utils/mime.d.ts.map +1 -0
  478. package/dist/sdk/coding-agent/utils/paths.d.ts +31 -0
  479. package/dist/sdk/coding-agent/utils/paths.d.ts.map +1 -0
  480. package/dist/sdk/coding-agent/utils/photon.d.ts +13 -0
  481. package/dist/sdk/coding-agent/utils/photon.d.ts.map +1 -0
  482. package/dist/sdk/coding-agent/utils/pi-user-agent.d.ts +2 -0
  483. package/dist/sdk/coding-agent/utils/pi-user-agent.d.ts.map +1 -0
  484. package/dist/sdk/coding-agent/utils/shell.d.ts +30 -0
  485. package/dist/sdk/coding-agent/utils/shell.d.ts.map +1 -0
  486. package/dist/sdk/coding-agent/utils/sleep.d.ts +5 -0
  487. package/dist/sdk/coding-agent/utils/sleep.d.ts.map +1 -0
  488. package/dist/sdk/coding-agent/utils/syntax-highlight.d.ts +12 -0
  489. package/dist/sdk/coding-agent/utils/syntax-highlight.d.ts.map +1 -0
  490. package/dist/sdk/coding-agent/utils/tools-manager.d.ts +3 -0
  491. package/dist/sdk/coding-agent/utils/tools-manager.d.ts.map +1 -0
  492. package/dist/sdk/coding-agent/utils/version-check.d.ts +15 -0
  493. package/dist/sdk/coding-agent/utils/version-check.d.ts.map +1 -0
  494. package/dist/sdk/coding-agent/utils/windows-self-update.d.ts +3 -0
  495. package/dist/sdk/coding-agent/utils/windows-self-update.d.ts.map +1 -0
  496. package/dist/server/agent-bridge.d.ts +308 -0
  497. package/dist/server/agent-bridge.d.ts.map +1 -0
  498. package/dist/server/handlers/errors.d.ts +26 -0
  499. package/dist/server/handlers/errors.d.ts.map +1 -0
  500. package/dist/server/handlers/paths-autocomplete.d.ts +45 -0
  501. package/dist/server/handlers/paths-autocomplete.d.ts.map +1 -0
  502. package/dist/server/handlers/projects.d.ts +58 -0
  503. package/dist/server/handlers/projects.d.ts.map +1 -0
  504. package/dist/server/handlers/queue.d.ts +27 -0
  505. package/dist/server/handlers/queue.d.ts.map +1 -0
  506. package/dist/server/handlers/sessions.d.ts +50 -0
  507. package/dist/server/handlers/sessions.d.ts.map +1 -0
  508. package/dist/server/paths.d.ts +51 -0
  509. package/dist/server/paths.d.ts.map +1 -0
  510. package/dist/server/session-stream.d.ts +379 -0
  511. package/dist/server/session-stream.d.ts.map +1 -0
  512. package/dist/server/shutdown.d.ts +102 -0
  513. package/dist/server/shutdown.d.ts.map +1 -0
  514. package/dist/server/storage.d.ts +287 -0
  515. package/dist/server/storage.d.ts.map +1 -0
  516. package/dist/server/title-generator.d.ts +25 -0
  517. package/dist/server/title-generator.d.ts.map +1 -0
  518. package/dist/server/wire.d.ts +448 -0
  519. package/dist/server/wire.d.ts.map +1 -0
  520. package/dist/studio-binding.d.ts +44 -0
  521. package/dist/studio-binding.d.ts.map +1 -0
  522. package/dist/studio-binding.js +1 -1
  523. package/package.json +11 -1
@@ -282,16 +282,15 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
282
282
  "",
283
283
  "## Pi Extension API Reference (HARD-CODED — DO NOT RESEARCH)",
284
284
  "",
285
- "You are running inside **pi**, a coding agent harness. You do NOT need to research",
286
- "what pi is or how it works this knowledge is provided here. Jump straight to",
287
- "analyzing the project and generating extensions.",
285
+ "This section is the canonical extension API. Use it directly do NOT research",
286
+ "pi internals. For the full guide, see `cli-node/docs/extensions.md` in the pi repo.",
288
287
  "",
289
288
  "### Extension Entry Point",
290
289
  "",
291
290
  "Every extension is a TypeScript file exporting a single default `activate` function:",
292
291
  "",
293
292
  "```typescript",
294
- "import type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";",
293
+ "import type { ExtensionAPI, ToolDefinition } from \"@aexol/spectral\";",
295
294
  "export default function activate(pi: ExtensionAPI): void {",
296
295
  " // Register tools, commands, event handlers here",
297
296
  "}",
@@ -300,94 +299,215 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
300
299
  "Extensions live in: `.spectral/extensions/` (project-local) or `~/.spectral/agent/extensions/` (user-global).",
301
300
  "Auto-research generates extensions into `.spectral/extensions/auto-research/<name>/`.",
302
301
  "",
303
- "### Tools (pi.registerTool)",
302
+ "### Tools: pi.registerTool(tool)",
304
303
  "",
305
- "The primary extension mechanism. Tools become available to the agent during conversations.",
304
+ "The primary extension mechanism. Tools become callable by the LLM.",
306
305
  "",
307
306
  "```typescript",
308
307
  "import { Type } from \"typebox\"; // Built-in, zero-dependency schema validation",
309
308
  "",
310
309
  "pi.registerTool({",
311
- " name: \"tool_name\", // snake_case, unique",
312
- " description: \"What this tool does\", // Used by the agent to decide when to call",
313
- " parameters: Type.Object({ // TypeBox schema for typed params",
314
- " input: Type.String({ description: \"The input to process\" }),",
315
- " // Optional params: Type.Optional(Type.String())",
316
- " }),",
317
- " handler: async (params, ctx) => {",
318
- " // ctx.session?.cwd current working directory",
319
- " // ctx.bash(cmd) — run shell commands",
320
- " // ctx.read(path) — read files",
321
- " // ctx.write(path, content) — write files",
310
+ " name: \"tool_name\", // snake_case, globally unique",
311
+ " label: \"Tool Name\", // Human-readable label for UI",
312
+ " description: \"What this tool does\", // Used by the LLM to decide when to call",
313
+ " parameters: { // JSON Schema object (required)",
314
+ " type: \"object\",",
315
+ " properties: {",
316
+ " input: { type: \"string\", description: \"The input to process\" },",
317
+ " mode: { type: \"string\", enum: [\"fast\", \"deep\"] },",
318
+ " },",
319
+ " required: [\"input\"],",
320
+ " },",
321
+ " // OR use TypeBox for richer schemas:",
322
+ " // parameters: Type.Object({",
323
+ " // input: Type.String({ description: \"\" }),",
324
+ " // mode: Type.Optional(Type.Union([Type.Literal(\"fast\"), Type.Literal(\"deep\")])),",
325
+ " // }),",
326
+ " async execute(toolCallId, params, signal, onUpdate, ctx) {",
327
+ " // toolCallId — unique call identifier (string)",
328
+ " // params — validated against your schema",
329
+ " // signal — AbortSignal | undefined",
330
+ " // onUpdate — send partial results (params) => void",
331
+ " // ctx — ExtensionContext",
332
+ "",
333
+ " // For long operations, stream partial updates:",
334
+ " onUpdate?.({ stage: \"starting\", progress: 0 });",
335
+ " // ... work ...",
336
+ " onUpdate?.({ stage: \"done\", progress: 100 });",
337
+ "",
322
338
  " return {",
323
339
  " content: [{ type: \"text\", text: \"Result string\" }],",
324
- " // isError: true // set this to signal failure",
340
+ " details: {}, // arbitrary structured data",
325
341
  " };",
326
342
  " },",
343
+ " executionMode: \"sequential\", // optional: \"sequential\" | \"parallel\"",
344
+ " promptSnippet: \"One-liner for prompt\", // optional",
345
+ " promptGuidelines: [\"Extra guidance\"], // optional: appended to system prompt",
346
+ " prepareArguments(args) { // optional: shim args before validation",
347
+ " return args;",
348
+ " },",
327
349
  "});",
328
350
  "```",
329
351
  "",
330
- "### Commands (pi.registerCommand)",
352
+ "**Error handling:** Return error content, don't throw:",
353
+ "",
354
+ "```typescript",
355
+ "async execute() {",
356
+ " try {",
357
+ " // ... work ...",
358
+ " } catch (err: any) {",
359
+ " return {",
360
+ " content: [{ type: \"text\", text: `Error: ${err.message}` }],",
361
+ " details: { isError: true },",
362
+ " };",
363
+ " }",
364
+ "}",
365
+ "```",
366
+ "",
367
+ "### Commands: pi.registerCommand(name, options)",
331
368
  "",
332
- "Custom slash commands the user can type:",
369
+ "Register slash-commands invoked as `/command-name`:",
333
370
  "",
334
371
  "```typescript",
335
372
  "pi.registerCommand({",
336
373
  " name: \"my-command\",",
337
374
  " description: \"What /my-command does\",",
338
- " execute: async (args: string[], ctx) => {",
375
+ " async execute(args: string[], ctx: ExtensionContext) {",
339
376
  " return { content: [{ type: \"text\", text: \"Done\" }] };",
340
377
  " },",
341
378
  "});",
342
379
  "```",
343
380
  "",
344
- "### Event Interception (pi.on)",
345
- "",
346
- "React to agent lifecycle events. Available events: `tool_call` (before a tool runs),",
347
- "`session_start`, `session_shutdown`, `context` (prompt assembly), `before_agent_start`.",
381
+ "### Events: pi.on(eventType, handler)",
382
+ "",
383
+ "Hook into the agent lifecycle. Handlers can observe, modify (return result), or block.",
384
+ "",
385
+ "| Event | When | Return type |",
386
+ "|-------|------|-------------|",
387
+ "| `resources_discover` | After session start | `ResourcesDiscoverResult` — add skill/prompt/theme paths |",
388
+ "| `session_start` | Session loaded | — (void) |",
389
+ "| `session_before_switch` | Before switching session | `SessionBeforeSwitchResult` — can cancel |",
390
+ "| `session_before_fork` | Before forking | `SessionBeforeForkResult` — can cancel |",
391
+ "| `session_before_compact` | Before compaction | `SessionBeforeCompactResult` — can cancel/provide compaction |",
392
+ "| `session_compact` | After compaction | — |",
393
+ "| `session_before_tree` | Before tree navigation | `SessionBeforeTreeResult` — can cancel/provide summary |",
394
+ "| `session_tree` | After tree navigation | — |",
395
+ "| `session_shutdown` | Extension runtime teardown | — |",
396
+ "| `before_agent_start` | After user prompt, before LLM call | `BeforeAgentStartEventResult` — modify system prompt |",
397
+ "| `agent_start` | Agent loop starts | — |",
398
+ "| `agent_end` | Agent loop ends | — |",
399
+ "| `turn_start` | Each turn starts | — |",
400
+ "| `turn_end` | Each turn ends | — |",
401
+ "| `message_start` | Message begins | — |",
402
+ "| `message_update` | Token-by-token streaming | — |",
403
+ "| `message_end` | Message finalizes | `MessageEndEventResult` — replace message |",
404
+ "| `tool_execution_start` | Tool starts executing | — |",
405
+ "| `tool_execution_update` | Tool sends partial result | — |",
406
+ "| `tool_execution_end` | Tool finishes | — |",
407
+ "| `tool_call` | Before tool executes | `ToolCallEventResult` — block/modify input |",
408
+ "| `tool_result` | After tool executes | `ToolResultEventResult` — modify result |",
409
+ "| `model_select` | Model changes | — |",
410
+ "| `user_bash` | User runs ! command | `UserBashEventResult` — override execution |",
411
+ "| `input` | User input received | `InputEventResult` — transform/block/continue |",
412
+ "| `context` | Before each LLM call | `ContextEventResult` — modify messages |",
413
+ "| `before_provider_request` | Before provider API call | Replace payload |",
414
+ "| `after_provider_response` | After provider API response | — |",
348
415
  "",
349
416
  "```typescript",
350
- "pi.on(\"tool_call\", (event) => {",
351
- " // event.name tool being called",
352
- " // event.params tool arguments",
353
- " // Can modify or observe tool calls",
417
+ "pi.on(\"before_agent_start\", (event, ctx) => {",
418
+ " // Inject extra instructions into every turn:",
419
+ " return { systemPrompt: event.systemPrompt + \"\\nExtra rules...\" };",
420
+ "});",
421
+ "",
422
+ "pi.on(\"tool_call\", (event, ctx) => {",
423
+ " // event.name, event.params, event.toolCallId",
424
+ " // Return { blocked: true, reason: \"...\" } to block",
425
+ " // Return { params: {...} } to mutate input",
354
426
  "});",
355
427
  "```",
356
428
  "",
357
- "### Model Access (LLM-powered extensions)",
429
+ "### Actions: pi.sendMessage / pi.sendUserMessage / pi.exec",
430
+ "",
431
+ "```typescript",
432
+ "// Send custom messages into the session stream:",
433
+ "pi.sendMessage({ customType: \"my-event\", content: \"Something happened!\", display: \"Notification\", details: {} });",
434
+ "pi.sendUserMessage(\"Continue with the task.\");",
435
+ "",
436
+ "// Run a shell command:",
437
+ "const result = await pi.exec(\"npm\", [\"test\"], { cwd: \"/path\" });",
438
+ "// result.exitCode, result.stdout, result.stderr",
439
+ "```",
440
+ "",
441
+ "### Model / Thinking Control",
442
+ "",
443
+ "```typescript",
444
+ "// Get/set thinking level (off | minimal | low | medium | high)",
445
+ "pi.getThinkingLevel();",
446
+ "pi.setThinkingLevel(\"high\");",
447
+ "",
448
+ "// Tool visibility management",
449
+ "pi.getActiveTools(); // string[] — currently enabled tool names",
450
+ "pi.getAllTools(); // ToolInfo[] — all registered tools",
451
+ "pi.setActiveTools([\"bash\", \"read\", \"write\", \"edit\", \"my_tool\"]);",
452
+ "```",
453
+ "",
454
+ "### CLI Flags: pi.registerFlag",
455
+ "",
456
+ "```typescript",
457
+ "pi.registerFlag(\"api-endpoint\", { description: \"Override API endpoint\", type: \"string\" });",
458
+ "const endpoint = pi.getFlag(\"api-endpoint\") as string;",
459
+ "```",
358
460
  "",
359
- "Extensions can call LLMs to build AI-powered features:",
461
+ "### Provider Registration: pi.registerProvider",
360
462
  "",
361
463
  "```typescript",
362
- "// Discover available models",
363
- "const models = pi.modelRegistry.list();",
364
- "const model = pi.modelRegistry.find(\"claude-sonnet-4-5\");",
464
+ "pi.registerProvider(\"my-proxy\", {",
465
+ " baseUrl: \"https://proxy.example.com\",",
466
+ " apiKey: \"sk-...\",",
467
+ " api: \"anthropic-messages\",",
468
+ " models: [{ id: \"custom\", name: \"Custom\", reasoning: false, input: [\"text\"],",
469
+ " cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },",
470
+ " contextWindow: 200000, maxTokens: 16384 }],",
471
+ "});",
472
+ "```",
365
473
  "",
366
- "// Switch the active model for the current turn",
367
- "const switched = pi.setModel(model.id); // returns false if no API key",
474
+ "### Keyboard Shortcuts: pi.registerShortcut",
368
475
  "",
369
- "// For complex multi-step AI pipelines, spawn a subagent:",
370
- "// (see subagent extension pattern below)",
476
+ "```typescript",
477
+ "pi.registerShortcut(\"ctrl+shift+k\", { description: \"Run custom action\", handler(ctx) { /* ... */ } });",
371
478
  "```",
372
479
  "",
480
+ "### The ExtensionContext (ctx)",
481
+ "",
482
+ "Passed to every execute/handler. Key properties:",
483
+ "",
484
+ "| Property/method | Description |",
485
+ "|-----------------|-------------|",
486
+ "| `ctx.cwd` | Current working directory (string) |",
487
+ "| `ctx.hasUI` | Whether interactive UI is available (boolean) |",
488
+ "| `ctx.model` | Current model object (Model \\| undefined) |",
489
+ "| `ctx.modelRegistry` | List/find available models |",
490
+ "| `ctx.signal` | Current AbortSignal (undefined if no stream) |",
491
+ "| `ctx.abort()` | Abort the current operation |",
492
+ "| `ctx.isIdle()` | Whether the agent is not streaming |",
493
+ "| `ctx.getSystemPrompt()` | Get the full system prompt (string) |",
494
+ "| `ctx.getContextUsage()` | Token usage info |",
495
+ "| `ctx.compact(options?)` | Trigger context compaction |",
496
+ "| `ctx.shutdown()` | Gracefully exit |",
497
+ "| `ctx.ui.select(prompt, choices)` | Ask the user to pick from a list |",
498
+ "| `ctx.ui.confirm(prompt)` | Ask the user Yes/No |",
499
+ "| `ctx.ui.notify(message)` | Show a notification |",
500
+ "",
373
501
  "### Available Packages (npm dependencies)",
374
502
  "",
375
503
  "Extensions run as Node.js TypeScript modules. These packages are available:",
376
- "- `@mariozechner/pi-coding-agent` — ExtensionAPI type",
377
- "- `@mariozechner/pi-ai` — AI types and utilities",
504
+ "- `@aexol/spectral` — ExtensionAPI, all event types, ToolDefinition, defineTool, type guards",
378
505
  "- `typebox` — Zero-dependency runtime type validation",
379
506
  "- All `node:*` built-ins: `fs`, `path`, `child_process`, `os`, `crypto`, etc.",
380
507
  "- Any npm package already in the project's node_modules",
381
508
  "",
382
- "```typescript",
383
- "import * as fs from \"node:fs\";",
384
- "import * as path from \"node:path\";",
385
- "import { execSync } from \"node:child_process\";",
386
- "```",
387
- "",
388
- "### Pi's Built-in Tools (what the agent already has)",
509
+ "### Pi's Built-in Tools (what the agent already has — DO NOT reimplement)",
389
510
  "",
390
- "The agent already has these tools — do NOT reimplement them:",
391
511
  "- `read` — Read file contents",
392
512
  "- `write` — Create/overwrite files",
393
513
  "- `edit` — Precise text replacement in files",
@@ -395,13 +515,13 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
395
515
  "- `grep` — Search file contents with regex",
396
516
  "- `find` — Search files by name/pattern",
397
517
  "- `ls` — List directory contents",
518
+ "- `subagent` — Spawn isolated sub-agents",
398
519
  "- `recall` — Recall compressed memory observations",
399
- "- `mcp` — MCP server gateway (if MCP extension is active)",
520
+ "- `mcp` — MCP server gateway",
521
+ "- `kanban_list/get/create/update/move/next/delete` — Kanban board (if bound)",
400
522
  "",
401
523
  "### Extension File Structure",
402
524
  "",
403
- "Each extension is a directory under `.spectral/extensions/auto-research/`:",
404
- "",
405
525
  "```",
406
526
  ".spectral/extensions/auto-research/",
407
527
  " <extension-name>/",
@@ -410,29 +530,14 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
410
530
  " state.json # [optional] Persisted state (for stateful extensions)",
411
531
  "```",
412
532
  "",
413
- "### Handler Return Types",
414
- "",
415
- "All handlers (tools, commands) return content blocks:",
416
- "",
417
- "```typescript",
418
- "// Success:",
419
- "return { content: [{ type: \"text\", text: \"Result\" }] };",
420
- "",
421
- "// Error:",
422
- "return {",
423
- " content: [{ type: \"text\", text: \"Error message\" }],",
424
- " isError: true,",
425
- "};",
426
- "```",
427
- "",
428
533
  "### Common Extension Patterns",
429
534
  "",
430
- "1. **Shell wrapper** — Use `ctx.bash()` inside a tool handler to run commands",
431
- "2. **File processor** — Use `ctx.read()`/`ctx.write()` to process project files",
535
+ "1. **Shell wrapper** — Use `execSync` from \"node:child_process\" to run project commands",
536
+ "2. **File processor** — Use `node:fs` to read/write project files",
432
537
  "3. **LLM-powered** — Use `pi.modelRegistry` to call AI models for smart processing",
433
538
  "4. **Event listener** — Use `pi.on()` to react to agent lifecycle events",
434
539
  "5. **Stateful** — Use `node:fs` to persist state as JSON between calls",
435
- "6. **Subagent** — Spawn pi subprocesses for isolated analysis tasks",
540
+ "6. **Subagent** — Use the `subagent` tool for isolated analysis tasks",
436
541
  "",
437
542
  "---",
438
543
  "",
@@ -0,0 +1,126 @@
1
+ /**
2
+ * RelayClient — long-lived WebSocket connection to the Aexol backend's
3
+ * `/agent-connection` endpoint.
4
+ *
5
+ * Responsibilities:
6
+ * - Open and maintain a single WS to the relay, authenticated with the
7
+ * machine JWT via `Authorization: Bearer <jwt>`.
8
+ * - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
9
+ * `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
10
+ * rely on the backend pings rather than emitting our own (single source
11
+ * of liveness, no jitter on our side).
12
+ * - **Watchdog timer:** tracks `lastActivityMs` on every received frame /
13
+ * ping. Every 15 s, if no activity within `WATCHDOG_MS` (120 s = 2×
14
+ * backend timeout), force-closes the socket (4001 "watchdog-timeout")
15
+ * and triggers a reconnect. Detects silent backend death (Docker OOM
16
+ * kill, network partition without TCP RST) where the socket stays open
17
+ * but no data flows.
18
+ * - **Pre-reconnect health check:** before opening a new WS, does a quick
19
+ * HTTP GET to `backendUrl/health` with a 5 s timeout. If the backend is
20
+ * unhealthy or unreachable, skips the WS attempt and re-schedules. This
21
+ * avoids a slow TCP connect timeout (up to 75 s on some platforms) when
22
+ * the backend is down.
23
+ * - On unexpected close, reconnect forever with exponential backoff +
24
+ * ±20% jitter, capped at 30s. There is no "give up" state — if the
25
+ * machine is offline for hours, we just keep trying. Operators can
26
+ * `Ctrl-C` to stop.
27
+ * - Buffer outbound frames in a small queue while the socket is closed.
28
+ * Capped at 100 frames; oldest is dropped on overflow.
29
+ *
30
+ * Events (typed via `RelayClientEvents`):
31
+ * - `open` - connected and welcomed
32
+ * - `welcome` - backend `{kind:"welcome"}` frame
33
+ * - `frame` - any non-pong, non-welcome frame
34
+ * - `close` - socket closed (we may reconnect after)
35
+ * - `error` - non-fatal error (parse failure, send failure)
36
+ * - `reconnect-scheduled` - emitted with the delay in ms before each retry
37
+ *
38
+ * Threading model: `node:events` is single-threaded; all callbacks fire on
39
+ * the same event loop turn. Listeners must be cheap.
40
+ */
41
+ import { EventEmitter } from "node:events";
42
+ import WebSocket from "ws";
43
+ export interface RelayClientOptions {
44
+ /** Full WS URL, e.g. wss://api.aexol.ai/agent-connection */
45
+ relayUrl: string;
46
+ /** Bearer JWT for the WS handshake. */
47
+ machineJwt: string;
48
+ /**
49
+ * Backend HTTP(S) base URL for the pre-reconnect health check
50
+ * (`GET <backendUrl>/health`). When omitted, the health check is
51
+ * skipped (tests, local-only deploys without a /health endpoint).
52
+ */
53
+ backendUrl?: string;
54
+ /**
55
+ * Override the WebSocket constructor (tests inject a fake or a wrapper).
56
+ * Default: `ws` package's `WebSocket`.
57
+ */
58
+ webSocketImpl?: typeof WebSocket;
59
+ /**
60
+ * Override `fetch` (tests inject a stub for health checks).
61
+ * Default: global `fetch`.
62
+ */
63
+ fetchImpl?: typeof fetch;
64
+ /**
65
+ * Optional logger. Defaults to console. Tests pass a noop.
66
+ */
67
+ logger?: Pick<Console, "log" | "warn" | "error">;
68
+ /**
69
+ * Override `process.exit` for tests. Called when the backend evicts us
70
+ * with `replaced-by-newer-registration` to avoid a reconnect ping-pong.
71
+ * Default: `process.exit`.
72
+ */
73
+ exit?: (code: number) => never;
74
+ }
75
+ /** Strongly-typed event surface. Used for ergonomic `.on(...)` callsites. */
76
+ export interface RelayFrame {
77
+ /** Echoed-out shape; concrete type varies by Batch. */
78
+ kind?: string;
79
+ [key: string]: unknown;
80
+ }
81
+ export declare class RelayClient extends EventEmitter {
82
+ private readonly relayUrl;
83
+ private readonly machineJwt;
84
+ private readonly backendUrl;
85
+ private readonly WS;
86
+ private readonly fetchImpl;
87
+ private readonly logger;
88
+ private readonly exit;
89
+ private ws;
90
+ private disposed;
91
+ private reconnectAttempt;
92
+ private reconnectTimer;
93
+ private sendQueue;
94
+ /** Timestamp of last received frame / ping — drives the watchdog. */
95
+ private lastActivityMs;
96
+ private watchdogTimer;
97
+ constructor(opts: RelayClientOptions);
98
+ /** Open the connection. Idempotent — calling twice is a no-op. */
99
+ connect(): void;
100
+ /**
101
+ * Send a frame. If the socket is open it goes immediately; otherwise
102
+ * it's queued (capped at 100 — oldest dropped) and flushed on the next
103
+ * successful `open`.
104
+ *
105
+ * Returns `true` if the frame was sent or queued, `false` if it was
106
+ * dropped due to dispose.
107
+ */
108
+ send(frame: RelayFrame | string): boolean;
109
+ /**
110
+ * Close the connection and stop reconnecting. After dispose, this client
111
+ * is dead — create a new one to reconnect.
112
+ */
113
+ dispose(): void;
114
+ private openSocket;
115
+ private startWatchdog;
116
+ private stopWatchdog;
117
+ /**
118
+ * Pre-reconnect health check: quick HTTP GET to `<backendUrl>/health`.
119
+ * Returns true when the backend is reachable (or when no backendUrl is
120
+ * configured, which skips the check entirely). Returns false when the
121
+ * backend is unhealthy/down — the caller should re-schedule.
122
+ */
123
+ private healthCheck;
124
+ private scheduleReconnect;
125
+ }
126
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,SAAS,MAAM,IAAI,CAAC;AAqB3B,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAE/C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,SAAS,CAAgB;IAEjC,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAA+B;gBAExC,IAAI,EAAE,kBAAkB;IAWpC,kEAAkE;IAClE,OAAO,IAAI,IAAI;IAMf;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO;IAqBzC;;;OAGG;IACH,OAAO,IAAI,IAAI;IA2Bf,OAAO,CAAC,UAAU;IAgHlB,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,YAAY;IAOpB;;;;;OAKG;YACW,WAAW;YA8BX,iBAAiB;CAmDhC"}