@adonis-agora/agent 0.76.2 → 0.77.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 (287) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/dist/providers/agent_provider.d.ts.map +1 -1
  3. package/dist/providers/agent_provider.js +9 -0
  4. package/dist/providers/agent_provider.js.map +1 -1
  5. package/dist/providers/mcp_provider.d.ts.map +1 -1
  6. package/dist/providers/mcp_provider.js +46 -10
  7. package/dist/providers/mcp_provider.js.map +1 -1
  8. package/dist/providers/poppy_connections_provider.d.ts +17 -0
  9. package/dist/providers/poppy_connections_provider.d.ts.map +1 -0
  10. package/dist/providers/poppy_connections_provider.js +186 -0
  11. package/dist/providers/poppy_connections_provider.js.map +1 -0
  12. package/dist/providers/poppy_provider.d.ts +12 -0
  13. package/dist/providers/poppy_provider.d.ts.map +1 -0
  14. package/dist/providers/poppy_provider.js +159 -0
  15. package/dist/providers/poppy_provider.js.map +1 -0
  16. package/dist/src/a2a/handler.d.ts.map +1 -1
  17. package/dist/src/a2a/handler.js +4 -2
  18. package/dist/src/a2a/handler.js.map +1 -1
  19. package/dist/src/a2a/turn.d.ts +27 -4
  20. package/dist/src/a2a/turn.d.ts.map +1 -1
  21. package/dist/src/a2a/turn.js +66 -12
  22. package/dist/src/a2a/turn.js.map +1 -1
  23. package/dist/src/action-proposal-approval.d.ts.map +1 -1
  24. package/dist/src/action-proposal-approval.js +3 -3
  25. package/dist/src/action-proposal-approval.js.map +1 -1
  26. package/dist/src/action-proposal-listeners.d.ts +12 -0
  27. package/dist/src/action-proposal-listeners.d.ts.map +1 -0
  28. package/dist/src/action-proposal-listeners.js +27 -0
  29. package/dist/src/action-proposal-listeners.js.map +1 -0
  30. package/dist/src/action-proposal-receipt.d.ts +4 -0
  31. package/dist/src/action-proposal-receipt.d.ts.map +1 -1
  32. package/dist/src/action-proposal-receipt.js +3 -1
  33. package/dist/src/action-proposal-receipt.js.map +1 -1
  34. package/dist/src/action-proposal-worker.d.ts +6 -1
  35. package/dist/src/action-proposal-worker.d.ts.map +1 -1
  36. package/dist/src/action-proposal-worker.js +10 -1
  37. package/dist/src/action-proposal-worker.js.map +1 -1
  38. package/dist/src/agent-loop.d.ts.map +1 -1
  39. package/dist/src/agent-loop.js +8 -5
  40. package/dist/src/agent-loop.js.map +1 -1
  41. package/dist/src/channels/handler.d.ts +10 -0
  42. package/dist/src/channels/handler.d.ts.map +1 -1
  43. package/dist/src/channels/handler.js +44 -1
  44. package/dist/src/channels/handler.js.map +1 -1
  45. package/dist/src/channels/texts.d.ts +9 -0
  46. package/dist/src/channels/texts.d.ts.map +1 -1
  47. package/dist/src/channels/texts.js +4 -0
  48. package/dist/src/channels/texts.js.map +1 -1
  49. package/dist/src/client/sse.d.ts.map +1 -1
  50. package/dist/src/client/sse.js +3 -0
  51. package/dist/src/client/sse.js.map +1 -1
  52. package/dist/src/define_config.d.ts +3 -0
  53. package/dist/src/define_config.d.ts.map +1 -1
  54. package/dist/src/define_config.js.map +1 -1
  55. package/dist/src/genui/kit/styles.d.ts.map +1 -1
  56. package/dist/src/genui/kit/styles.js +11 -2
  57. package/dist/src/genui/kit/styles.js.map +1 -1
  58. package/dist/src/genui/sandbox-styles.js +1 -1
  59. package/dist/src/genui/sandbox-styles.js.map +1 -1
  60. package/dist/src/genui/sandbox-theme.d.ts +6 -1
  61. package/dist/src/genui/sandbox-theme.d.ts.map +1 -1
  62. package/dist/src/genui/sandbox-theme.js +9 -5
  63. package/dist/src/genui/sandbox-theme.js.map +1 -1
  64. package/dist/src/genui/sandbox.d.ts.map +1 -1
  65. package/dist/src/genui/sandbox.js +1 -0
  66. package/dist/src/genui/sandbox.js.map +1 -1
  67. package/dist/src/index.d.ts +2 -1
  68. package/dist/src/index.d.ts.map +1 -1
  69. package/dist/src/index.js +2 -1
  70. package/dist/src/index.js.map +1 -1
  71. package/dist/src/mcp/auth.d.ts +17 -0
  72. package/dist/src/mcp/auth.d.ts.map +1 -1
  73. package/dist/src/mcp/auth.js +56 -1
  74. package/dist/src/mcp/auth.js.map +1 -1
  75. package/dist/src/mcp/discovery.d.ts +13 -2
  76. package/dist/src/mcp/discovery.d.ts.map +1 -1
  77. package/dist/src/mcp/discovery.js +17 -2
  78. package/dist/src/mcp/discovery.js.map +1 -1
  79. package/dist/src/mcp/index.d.ts +1 -1
  80. package/dist/src/mcp/index.d.ts.map +1 -1
  81. package/dist/src/mcp/index.js.map +1 -1
  82. package/dist/src/mcp/scope.d.ts +13 -0
  83. package/dist/src/mcp/scope.d.ts.map +1 -0
  84. package/dist/src/mcp/scope.js +24 -0
  85. package/dist/src/mcp/scope.js.map +1 -0
  86. package/dist/src/mcp/server.d.ts +6 -1
  87. package/dist/src/mcp/server.d.ts.map +1 -1
  88. package/dist/src/mcp/server.js +1 -1
  89. package/dist/src/mcp/server.js.map +1 -1
  90. package/dist/src/poppy/auth.d.ts +77 -0
  91. package/dist/src/poppy/auth.d.ts.map +1 -0
  92. package/dist/src/poppy/auth.js +16 -0
  93. package/dist/src/poppy/auth.js.map +1 -0
  94. package/dist/src/poppy/conversations.d.ts +249 -0
  95. package/dist/src/poppy/conversations.d.ts.map +1 -0
  96. package/dist/src/poppy/conversations.js +1017 -0
  97. package/dist/src/poppy/conversations.js.map +1 -0
  98. package/dist/src/poppy/define_config.d.ts +98 -0
  99. package/dist/src/poppy/define_config.d.ts.map +1 -0
  100. package/dist/src/poppy/define_config.js +11 -0
  101. package/dist/src/poppy/define_config.js.map +1 -0
  102. package/dist/src/poppy/endpoints.d.ts +25 -0
  103. package/dist/src/poppy/endpoints.d.ts.map +1 -0
  104. package/dist/src/poppy/endpoints.js +31 -0
  105. package/dist/src/poppy/endpoints.js.map +1 -0
  106. package/dist/src/poppy/handler.d.ts +80 -0
  107. package/dist/src/poppy/handler.d.ts.map +1 -0
  108. package/dist/src/poppy/handler.js +362 -0
  109. package/dist/src/poppy/handler.js.map +1 -0
  110. package/dist/src/poppy/index.d.ts +17 -0
  111. package/dist/src/poppy/index.d.ts.map +1 -0
  112. package/dist/src/poppy/index.js +9 -0
  113. package/dist/src/poppy/index.js.map +1 -0
  114. package/dist/src/poppy/protocol.d.ts +132 -0
  115. package/dist/src/poppy/protocol.d.ts.map +1 -0
  116. package/dist/src/poppy/protocol.js +178 -0
  117. package/dist/src/poppy/protocol.js.map +1 -0
  118. package/dist/src/poppy/redis-store.d.ts +27 -0
  119. package/dist/src/poppy/redis-store.d.ts.map +1 -0
  120. package/dist/src/poppy/redis-store.js +148 -0
  121. package/dist/src/poppy/redis-store.js.map +1 -0
  122. package/dist/src/poppy/runtime.d.ts +6 -0
  123. package/dist/src/poppy/runtime.d.ts.map +1 -0
  124. package/dist/src/poppy/runtime.js +12 -0
  125. package/dist/src/poppy/runtime.js.map +1 -0
  126. package/dist/src/poppy/server_middleware.d.ts +11 -0
  127. package/dist/src/poppy/server_middleware.d.ts.map +1 -0
  128. package/dist/src/poppy/server_middleware.js +16 -0
  129. package/dist/src/poppy/server_middleware.js.map +1 -0
  130. package/dist/src/poppy/store.d.ts +207 -0
  131. package/dist/src/poppy/store.d.ts.map +1 -0
  132. package/dist/src/poppy/store.js +444 -0
  133. package/dist/src/poppy/store.js.map +1 -0
  134. package/dist/src/poppy-client/api.d.ts +36 -0
  135. package/dist/src/poppy-client/api.d.ts.map +1 -0
  136. package/dist/src/poppy-client/api.js +77 -0
  137. package/dist/src/poppy-client/api.js.map +1 -0
  138. package/dist/src/poppy-client/bin/poppy-agent.d.ts +3 -0
  139. package/dist/src/poppy-client/bin/poppy-agent.d.ts.map +1 -0
  140. package/dist/src/poppy-client/bin/poppy-agent.js +9 -0
  141. package/dist/src/poppy-client/bin/poppy-agent.js.map +1 -0
  142. package/dist/src/poppy-client/browser.d.ts +24 -0
  143. package/dist/src/poppy-client/browser.d.ts.map +1 -0
  144. package/dist/src/poppy-client/browser.js +83 -0
  145. package/dist/src/poppy-client/browser.js.map +1 -0
  146. package/dist/src/poppy-client/cli/main.d.ts +2 -0
  147. package/dist/src/poppy-client/cli/main.d.ts.map +1 -0
  148. package/dist/src/poppy-client/cli/main.js +776 -0
  149. package/dist/src/poppy-client/cli/main.js.map +1 -0
  150. package/dist/src/poppy-client/cli/prompt.d.ts +13 -0
  151. package/dist/src/poppy-client/cli/prompt.d.ts.map +1 -0
  152. package/dist/src/poppy-client/cli/prompt.js +50 -0
  153. package/dist/src/poppy-client/cli/prompt.js.map +1 -0
  154. package/dist/src/poppy-client/company.d.ts +87 -0
  155. package/dist/src/poppy-client/company.d.ts.map +1 -0
  156. package/dist/src/poppy-client/company.js +336 -0
  157. package/dist/src/poppy-client/company.js.map +1 -0
  158. package/dist/src/poppy-client/conversations.d.ts +89 -0
  159. package/dist/src/poppy-client/conversations.d.ts.map +1 -0
  160. package/dist/src/poppy-client/conversations.js +332 -0
  161. package/dist/src/poppy-client/conversations.js.map +1 -0
  162. package/dist/src/poppy-client/discovery.d.ts +41 -0
  163. package/dist/src/poppy-client/discovery.d.ts.map +1 -0
  164. package/dist/src/poppy-client/discovery.js +217 -0
  165. package/dist/src/poppy-client/discovery.js.map +1 -0
  166. package/dist/src/poppy-client/dpop.d.ts +19 -0
  167. package/dist/src/poppy-client/dpop.d.ts.map +1 -0
  168. package/dist/src/poppy-client/dpop.js +43 -0
  169. package/dist/src/poppy-client/dpop.js.map +1 -0
  170. package/dist/src/poppy-client/errors.d.ts +50 -0
  171. package/dist/src/poppy-client/errors.d.ts.map +1 -0
  172. package/dist/src/poppy-client/errors.js +55 -0
  173. package/dist/src/poppy-client/errors.js.map +1 -0
  174. package/dist/src/poppy-client/http.d.ts +40 -0
  175. package/dist/src/poppy-client/http.d.ts.map +1 -0
  176. package/dist/src/poppy-client/http.js +95 -0
  177. package/dist/src/poppy-client/http.js.map +1 -0
  178. package/dist/src/poppy-client/identity.d.ts +61 -0
  179. package/dist/src/poppy-client/identity.d.ts.map +1 -0
  180. package/dist/src/poppy-client/identity.js +111 -0
  181. package/dist/src/poppy-client/identity.js.map +1 -0
  182. package/dist/src/poppy-client/identity_server.d.ts +29 -0
  183. package/dist/src/poppy-client/identity_server.d.ts.map +1 -0
  184. package/dist/src/poppy-client/identity_server.js +84 -0
  185. package/dist/src/poppy-client/identity_server.js.map +1 -0
  186. package/dist/src/poppy-client/index.d.ts +19 -0
  187. package/dist/src/poppy-client/index.d.ts.map +1 -0
  188. package/dist/src/poppy-client/index.js +18 -0
  189. package/dist/src/poppy-client/index.js.map +1 -0
  190. package/dist/src/poppy-client/keys.d.ts +13 -0
  191. package/dist/src/poppy-client/keys.d.ts.map +1 -0
  192. package/dist/src/poppy-client/keys.js +31 -0
  193. package/dist/src/poppy-client/keys.js.map +1 -0
  194. package/dist/src/poppy-client/llm.d.ts +31 -0
  195. package/dist/src/poppy-client/llm.d.ts.map +1 -0
  196. package/dist/src/poppy-client/llm.js +230 -0
  197. package/dist/src/poppy-client/llm.js.map +1 -0
  198. package/dist/src/poppy-client/mcp.d.ts +16 -0
  199. package/dist/src/poppy-client/mcp.d.ts.map +1 -0
  200. package/dist/src/poppy-client/mcp.js +57 -0
  201. package/dist/src/poppy-client/mcp.js.map +1 -0
  202. package/dist/src/poppy-client/open_url.d.ts +3 -0
  203. package/dist/src/poppy-client/open_url.d.ts.map +1 -0
  204. package/dist/src/poppy-client/open_url.js +13 -0
  205. package/dist/src/poppy-client/open_url.js.map +1 -0
  206. package/dist/src/poppy-client/signin.d.ts +59 -0
  207. package/dist/src/poppy-client/signin.d.ts.map +1 -0
  208. package/dist/src/poppy-client/signin.js +210 -0
  209. package/dist/src/poppy-client/signin.js.map +1 -0
  210. package/dist/src/poppy-client/sse.d.ts +15 -0
  211. package/dist/src/poppy-client/sse.d.ts.map +1 -0
  212. package/dist/src/poppy-client/sse.js +74 -0
  213. package/dist/src/poppy-client/sse.js.map +1 -0
  214. package/dist/src/poppy-client/store.d.ts +89 -0
  215. package/dist/src/poppy-client/store.d.ts.map +1 -0
  216. package/dist/src/poppy-client/store.js +79 -0
  217. package/dist/src/poppy-client/store.js.map +1 -0
  218. package/dist/src/poppy-client/token_client.d.ts +69 -0
  219. package/dist/src/poppy-client/token_client.d.ts.map +1 -0
  220. package/dist/src/poppy-client/token_client.js +154 -0
  221. package/dist/src/poppy-client/token_client.js.map +1 -0
  222. package/dist/src/poppy-client/types.d.ts +184 -0
  223. package/dist/src/poppy-client/types.d.ts.map +1 -0
  224. package/dist/src/poppy-client/types.js +8 -0
  225. package/dist/src/poppy-client/types.js.map +1 -0
  226. package/dist/src/poppy-client/util.d.ts +42 -0
  227. package/dist/src/poppy-client/util.d.ts.map +1 -0
  228. package/dist/src/poppy-client/util.js +122 -0
  229. package/dist/src/poppy-client/util.js.map +1 -0
  230. package/dist/src/poppy-connections/config.d.ts +134 -0
  231. package/dist/src/poppy-connections/config.d.ts.map +1 -0
  232. package/dist/src/poppy-connections/config.js +44 -0
  233. package/dist/src/poppy-connections/config.js.map +1 -0
  234. package/dist/src/poppy-connections/crypto.d.ts +12 -0
  235. package/dist/src/poppy-connections/crypto.d.ts.map +1 -0
  236. package/dist/src/poppy-connections/crypto.js +36 -0
  237. package/dist/src/poppy-connections/crypto.js.map +1 -0
  238. package/dist/src/poppy-connections/http.d.ts +63 -0
  239. package/dist/src/poppy-connections/http.d.ts.map +1 -0
  240. package/dist/src/poppy-connections/http.js +217 -0
  241. package/dist/src/poppy-connections/http.js.map +1 -0
  242. package/dist/src/poppy-connections/index.d.ts +14 -0
  243. package/dist/src/poppy-connections/index.d.ts.map +1 -0
  244. package/dist/src/poppy-connections/index.js +17 -0
  245. package/dist/src/poppy-connections/index.js.map +1 -0
  246. package/dist/src/poppy-connections/resume.d.ts +46 -0
  247. package/dist/src/poppy-connections/resume.d.ts.map +1 -0
  248. package/dist/src/poppy-connections/resume.js +109 -0
  249. package/dist/src/poppy-connections/resume.js.map +1 -0
  250. package/dist/src/poppy-connections/runtime.d.ts +4 -0
  251. package/dist/src/poppy-connections/runtime.d.ts.map +1 -0
  252. package/dist/src/poppy-connections/runtime.js +9 -0
  253. package/dist/src/poppy-connections/runtime.js.map +1 -0
  254. package/dist/src/poppy-connections/server_middleware.d.ts +10 -0
  255. package/dist/src/poppy-connections/server_middleware.d.ts.map +1 -0
  256. package/dist/src/poppy-connections/server_middleware.js +14 -0
  257. package/dist/src/poppy-connections/server_middleware.js.map +1 -0
  258. package/dist/src/poppy-connections/service.d.ts +179 -0
  259. package/dist/src/poppy-connections/service.d.ts.map +1 -0
  260. package/dist/src/poppy-connections/service.js +648 -0
  261. package/dist/src/poppy-connections/service.js.map +1 -0
  262. package/dist/src/poppy-connections/store.d.ts +139 -0
  263. package/dist/src/poppy-connections/store.d.ts.map +1 -0
  264. package/dist/src/poppy-connections/store.js +260 -0
  265. package/dist/src/poppy-connections/store.js.map +1 -0
  266. package/dist/src/poppy-connections/tools.d.ts +65 -0
  267. package/dist/src/poppy-connections/tools.d.ts.map +1 -0
  268. package/dist/src/poppy-connections/tools.js +574 -0
  269. package/dist/src/poppy-connections/tools.js.map +1 -0
  270. package/dist/src/react/core/approvals/use-action-proposals.d.ts +6 -1
  271. package/dist/src/react/core/approvals/use-action-proposals.d.ts.map +1 -1
  272. package/dist/src/react/core/approvals/use-action-proposals.js +18 -3
  273. package/dist/src/react/core/approvals/use-action-proposals.js.map +1 -1
  274. package/dist/src/react/core/use-agent-chat.d.ts +6 -0
  275. package/dist/src/react/core/use-agent-chat.d.ts.map +1 -1
  276. package/dist/src/react/core/use-agent-chat.js +47 -1
  277. package/dist/src/react/core/use-agent-chat.js.map +1 -1
  278. package/dist/src/tool-presentation.d.ts +6 -0
  279. package/dist/src/tool-presentation.d.ts.map +1 -1
  280. package/dist/src/tool-presentation.js +1 -0
  281. package/dist/src/tool-presentation.js.map +1 -1
  282. package/dist/src/types.d.ts +6 -0
  283. package/dist/src/types.d.ts.map +1 -1
  284. package/package.json +41 -2
  285. package/skills/agent-governance/SKILL.md +13 -2
  286. package/skills/agent-personas-agents/SKILL.md +1 -1
  287. package/skills/agent-tools/SKILL.md +20 -3
@@ -0,0 +1,249 @@
1
+ import { type A2aActionPolicy, type A2aTurnOutcome, type A2aTurnService } from '../a2a/turn.js';
2
+ import type { Actor } from '../types.js';
3
+ import type { PoppyPrincipal } from './auth.js';
4
+ import { type PoppyEvent, type PoppyEventMessage, type PoppyResponder, type PoppySendBody, type PoppySender, type PoppyStatus } from './protocol.js';
5
+ import { type PoppyConversationRecord, type PoppyStore } from './store.js';
6
+ /** What the hooks are told about a conversation. */
7
+ export interface PoppyHookContext {
8
+ conversationId: string;
9
+ conversation: PoppyConversationRecord;
10
+ /** Who the conversation's turns run as (its latest request); `null` before any. */
11
+ actor: Actor | null;
12
+ }
13
+ /**
14
+ * What {@link PoppyHandoffHooks.request} decided:
15
+ * - `'queued'` — someone will join: call {@link PoppyConversations.humanJoined} when they do, or
16
+ * {@link PoppyConversations.handoffUnavailable} if nobody can.
17
+ * - `'joined'` — a person took it now.
18
+ * - `{ unavailable }` — nobody can; the text is what the Company Agent says (§7.9).
19
+ */
20
+ export type PoppyHandoffDecision = 'queued' | 'joined' | {
21
+ unavailable: string;
22
+ };
23
+ /**
24
+ * How the app brings a person in (§7.9). Without these, a handoff is answered by the Company Agent
25
+ * saying no one is available — the conversation stays with the agent.
26
+ */
27
+ export interface PoppyHandoffHooks {
28
+ /** A person was asked for — by the Personal Agent (`requested`) or by the app (`company`). */
29
+ request(ctx: PoppyHookContext & {
30
+ by: 'requested' | 'company';
31
+ }): PoppyHandoffDecision | Promise<PoppyHandoffDecision>;
32
+ /**
33
+ * A message from the Personal Agent while a person handles the conversation or is being found —
34
+ * the agent does not answer those. Route it to your support tool.
35
+ */
36
+ message?(ctx: PoppyHookContext & {
37
+ message: PoppyEventMessage;
38
+ }): void | Promise<void>;
39
+ /** The conversation closed while a person was handling it or being found (§7.12). */
40
+ cancel?(ctx: PoppyHookContext): void | Promise<void>;
41
+ }
42
+ /** Notified when the Personal Agent opens or closes a Direct Conversation (§7.10). */
43
+ export interface PoppyDirectHooks {
44
+ opened?(ctx: PoppyHookContext & {
45
+ parentId: string;
46
+ }): void | Promise<void>;
47
+ closed?(ctx: PoppyHookContext & {
48
+ parentId: string;
49
+ }): void | Promise<void>;
50
+ }
51
+ /** What the Company Agent says on its own. */
52
+ export interface PoppyTexts {
53
+ /** A handoff with no one to take it (§7.9). */
54
+ handoffUnavailable: string;
55
+ /** A turn that failed before saying anything. */
56
+ failed: string;
57
+ /** Asked in a Direct Conversation alongside an `authorization` event (§7.11 SHOULD). */
58
+ signIn: string;
59
+ /** An action that ran — `{title}` is the app's confirmation title (default {@link formatPoppyAction}). */
60
+ actionSucceeded: string;
61
+ /** An approved action that did not run. `{title}`, `{error}`. */
62
+ actionFailed: string;
63
+ /** An action the policy refused. `{title}`. */
64
+ actionRejected: string;
65
+ }
66
+ export declare const DEFAULT_POPPY_TEXTS: PoppyTexts;
67
+ /** An action of the turn, as the reply's `data.actions` carries it. */
68
+ export type PoppyActionOutcome = A2aTurnOutcome;
69
+ /**
70
+ * Words an action for the reply's text (§7: the message must make sense without `data`). Return
71
+ * `null` to leave it out. Default {@link formatPoppyAction}.
72
+ */
73
+ export type PoppyActionFormatter = (action: PoppyActionOutcome, texts: PoppyTexts) => string | null | undefined;
74
+ /**
75
+ * Default wording: the status line from `texts` with the confirmation title (a question like
76
+ * "Log this dose?" loses its `?`), then the confirmation detail.
77
+ */
78
+ export declare function formatPoppyAction(action: PoppyActionOutcome, texts: PoppyTexts): string;
79
+ export interface PoppyConversationsOptions {
80
+ store: PoppyStore;
81
+ /** What runs a turn — `AgentService`, or an app's adapter (the A2A surface's contract). */
82
+ service: A2aTurnService & {
83
+ drive?(runId: string): Promise<void>;
84
+ };
85
+ /** The roles a tool declares, for matching the token's scopes. */
86
+ toolRoles: (toolName: string) => string[] | undefined;
87
+ /** The registered agent that answers. Omitted → the agent provider's default. */
88
+ agentName?: string;
89
+ /** What happens to `action` calls that park for approval. Default `'approve-delegated'`. */
90
+ actions?: A2aActionPolicy;
91
+ /** Give up on a turn after this many ms. Default 120 000. */
92
+ timeoutMs?: number;
93
+ /** Drive a durable run left pending, in this process (see `AgentService.drive`). Default `true`. */
94
+ drive?: boolean;
95
+ /** Map a principal without an actor to the app's actor. Default: `poppy:<hash>`. */
96
+ actorFor?: (principal: PoppyPrincipal, defaults: Actor) => Actor | Promise<Actor>;
97
+ /** Words each action of a reply. Default {@link formatPoppyAction}. */
98
+ formatAction?: PoppyActionFormatter;
99
+ handoff?: PoppyHandoffHooks;
100
+ direct?: PoppyDirectHooks;
101
+ texts?: Partial<PoppyTexts>;
102
+ /** Keep events this long, then prune them (a cursor there is `cursor_expired`). Default: forever. */
103
+ retentionMs?: number;
104
+ /** How often a waiting read looks for events another replica appended. Default 1000 ms. */
105
+ pollMs?: number;
106
+ /** Logs what fails outside a request (a turn, a hook). */
107
+ onError?: (error: unknown, context: string) => void;
108
+ }
109
+ /** What a read answers (§7.5). */
110
+ export interface PoppyReadResult {
111
+ conversation_id: string;
112
+ events: PoppyEvent[];
113
+ cursor: string | null;
114
+ has_more: boolean;
115
+ status: PoppyStatus;
116
+ responder: PoppyResponder;
117
+ }
118
+ /** What a stream yields: a stored event, or a provisional piece of text (§7.6). */
119
+ export type PoppyStreamItem = {
120
+ kind: 'event';
121
+ event: PoppyEvent;
122
+ } | {
123
+ kind: 'delta';
124
+ messageId: string;
125
+ text: string;
126
+ } | {
127
+ kind: 'state';
128
+ status: PoppyStatus;
129
+ };
130
+ /** The actor of a principal the resolver gave none: stable per (Personal Agent, its User). */
131
+ export declare function poppyActorId(clientId: string, userId: string): string;
132
+ /**
133
+ * Poppy conversations (§7) over the agent runtime: the state machine, the event log and the turns.
134
+ * HTTP-free — `createPoppyHandler` puts the protocol's requests on it, and the app drives the
135
+ * Company side through it (a person joining, their messages, `user_requested`).
136
+ *
137
+ * A conversation is an agent thread owned by the principal's actor. A user message is appended to
138
+ * the event log, and the log is the turn queue: a pump per conversation (one replica at a time,
139
+ * by lease) answers the messages after `turnSeq` in one turn, streams its text as `text-delta`,
140
+ * then appends the reply as a `message` event. A replica that finds a conversation `working` with
141
+ * no pump picks it up, so a reply survives the process that started it.
142
+ *
143
+ * @experimental Tracks Personal Agent Protocol Draft 0.1 (https://personalagentprotocol.org/docs/spec),
144
+ * a spec still in development: this API WILL change as the spec evolves — possibly in breaking
145
+ * ways, outside semver majors while it is a draft.
146
+ */
147
+ export declare class PoppyConversations {
148
+ #private;
149
+ private readonly options;
150
+ constructor(options: PoppyConversationsOptions);
151
+ /**
152
+ * The actor a principal's turns run as: the resolver's (`toActor`), else the app's `actorFor`,
153
+ * else — signed in — the ACCOUNT, `{ id: accountId }`, the way a PACT delegation runs as the
154
+ * account; signed out, `poppy:<hash>` (stable per Personal Agent and User, never an account).
155
+ * It ALWAYS carries `personal_agent` (what puts it behind `personalAgentGate`) and one
156
+ * `scope:<id>` role per account scope of a signed-in token — the roles a PACT delegation gives,
157
+ * so a tool written for personal agents gates both surfaces alike.
158
+ */
159
+ actorOf(principal: PoppyPrincipal): Promise<Actor>;
160
+ /** `POST {endpoint}` — start a conversation (or a Direct Conversation) with its first message. */
161
+ start(principal: PoppyPrincipal, body: PoppySendBody): Promise<{
162
+ status: number;
163
+ body: Record<string, unknown>;
164
+ conversationId: string;
165
+ }>;
166
+ /** `POST {endpoint}/{id}/messages` — another message (§7.3). */
167
+ send(principal: PoppyPrincipal, conversationId: string, body: PoppySendBody): Promise<{
168
+ status: number;
169
+ body: Record<string, unknown>;
170
+ }>;
171
+ /** `GET {endpoint}/{id}/events` without streaming — read (and wait for) events (§7.5). */
172
+ read(principal: PoppyPrincipal, conversationId: string, options: {
173
+ cursor?: string;
174
+ waitMs?: number;
175
+ }): Promise<PoppyReadResult>;
176
+ /** A read of a conversation already checked — also what a POST with `wait` answers (§7.3). */
177
+ readOwned(conversation: PoppyConversationRecord, options: {
178
+ cursor?: string;
179
+ waitMs?: number;
180
+ }): Promise<PoppyReadResult>;
181
+ /** Check a conversation is the principal's, for a caller that reads it afterwards. */
182
+ owned(principal: PoppyPrincipal, conversationId: string): Promise<PoppyConversationRecord>;
183
+ /**
184
+ * `GET {endpoint}/{id}/events` as SSE (§7.6): the events after `cursor`, then new ones as they
185
+ * come, with `text-delta` pieces of a reply being written in this process. Ends when `signal`
186
+ * aborts, or once the conversation is closed and every event was sent.
187
+ */
188
+ stream(conversation: PoppyConversationRecord, cursor: string | undefined, signal: AbortSignal): AsyncGenerator<PoppyStreamItem>;
189
+ /** `POST {endpoint}/{id}/handoff` — ask for a person at the Company (§7.9). */
190
+ requestHandoff(principal: PoppyPrincipal, conversationId: string): Promise<{
191
+ status: PoppyStatus;
192
+ responder: PoppyResponder;
193
+ }>;
194
+ /** `POST {endpoint}/{id}/close` — close the conversation (§7.12). */
195
+ closeByAgent(principal: PoppyPrincipal, conversationId: string): Promise<{
196
+ status: PoppyStatus;
197
+ responder: PoppyResponder;
198
+ }>;
199
+ /** Look a conversation up — for the app's own routing (a support tool, an admin page). */
200
+ get(conversationId: string): Promise<PoppyConversationRecord | null>;
201
+ /**
202
+ * Close a conversation (§7.12): its open Direct Conversation first, a pending handoff is
203
+ * cancelled, and a `closed` state event added. Nothing it started is undone. Idempotent.
204
+ */
205
+ close(conversationId: string): Promise<{
206
+ status: PoppyStatus;
207
+ responder: PoppyResponder;
208
+ }>;
209
+ /** The Company Agent hands off to a person on its own (§7.9) — e.g. from one of your tools. */
210
+ handoff(conversationId: string): Promise<{
211
+ status: PoppyStatus;
212
+ responder: PoppyResponder;
213
+ }>;
214
+ /** A person at the Company joined: `responder` becomes `human` (§7.7). */
215
+ humanJoined(conversationId: string): Promise<{
216
+ status: PoppyStatus;
217
+ responder: PoppyResponder;
218
+ }>;
219
+ /** The person left: the Company Agent answers again. */
220
+ humanLeft(conversationId: string): Promise<{
221
+ status: PoppyStatus;
222
+ responder: PoppyResponder;
223
+ }>;
224
+ /**
225
+ * No one could take a queued handoff: the Company Agent says why, and the conversation goes back
226
+ * to `idle` with the agent (§7.9).
227
+ */
228
+ handoffUnavailable(conversationId: string, reason?: string): Promise<{
229
+ status: PoppyStatus;
230
+ responder: PoppyResponder;
231
+ }>;
232
+ /**
233
+ * Add a Company message — a person's (`sender: 'human'`, while they handle the conversation) or
234
+ * an automated one. Answers the message's id.
235
+ */
236
+ postMessage(conversationId: string, message: {
237
+ text?: string;
238
+ data?: Record<string, unknown>;
239
+ sender: PoppySender;
240
+ }): Promise<string>;
241
+ /**
242
+ * Ask to talk with the User directly (§7.10): a `user_requested` event. Only the Personal Agent
243
+ * opens the Direct Conversation, once the User agrees.
244
+ */
245
+ requestUser(conversationId: string, reason: string): Promise<void>;
246
+ /** Stop pumping and waiting in this process (shutdown). */
247
+ shutdown(): void;
248
+ }
249
+ //# sourceMappingURL=conversations.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../../src/poppy/conversations.ts"],"names":[],"mappings":"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"}