@macro-inc/sdk 0.4.1 → 0.6.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 (228) hide show
  1. package/README.md +316 -21
  2. package/dist/{chunk-PTX2RV2N.js → chunk-4MI52GWV.js} +93 -1
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-HO75UE4Z.js} +146 -15
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-ZLBDES7U.js → chunk-SJ6S2GAT.js} +1271 -87
  6. package/dist/{chunk-AZJUIUIV.js → chunk-SK5CMXRV.js} +100 -14
  7. package/dist/{chunk-PZPTJI6F.js → chunk-TMTYN2UK.js} +229 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +202 -14
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +49 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +527 -9
  14. package/dist/generated/agent-reviews/index.d.ts +11 -9
  15. package/dist/generated/auth/index.d.ts +1 -1
  16. package/dist/generated/auth/index.js +1 -1
  17. package/dist/generated/auth/sdk.gen.d.ts +82 -16
  18. package/dist/generated/auth/types.gen.d.ts +768 -18
  19. package/dist/generated/calendar/types.gen.d.ts +10 -3
  20. package/dist/generated/cognition/index.d.ts +1 -1
  21. package/dist/generated/cognition/index.js +1 -1
  22. package/dist/generated/cognition/sdk.gen.d.ts +60 -6
  23. package/dist/generated/cognition/types.gen.d.ts +663 -106
  24. package/dist/generated/connection/types.gen.d.ts +1 -1
  25. package/dist/generated/contacts/index.d.ts +1 -1
  26. package/dist/generated/contacts/index.js +1 -1
  27. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  28. package/dist/generated/contacts/types.gen.d.ts +56 -0
  29. package/dist/generated/email/types.gen.d.ts +8 -2
  30. package/dist/generated/notification/index.d.ts +1 -1
  31. package/dist/generated/notification/index.js +1 -1
  32. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  33. package/dist/generated/notification/types.gen.d.ts +174 -1
  34. package/dist/generated/scheduled-action/index.d.ts +1 -1
  35. package/dist/generated/scheduled-action/index.js +1 -1
  36. package/dist/generated/scheduled-action/sdk.gen.d.ts +107 -2
  37. package/dist/generated/scheduled-action/types.gen.d.ts +2451 -479
  38. package/dist/generated/search/index.d.ts +1 -1
  39. package/dist/generated/search/types.gen.d.ts +50 -11
  40. package/dist/generated/storage/index.d.ts +1 -1
  41. package/dist/generated/storage/index.js +1 -1
  42. package/dist/generated/storage/sdk.gen.d.ts +511 -18
  43. package/dist/generated/storage/types.gen.d.ts +18528 -11395
  44. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  45. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  46. package/dist/src/entities/activity/entity.d.ts +7 -0
  47. package/dist/src/entities/activity/namespace.d.ts +58 -0
  48. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  49. package/dist/src/entities/agent-sessions/activity.d.ts +12 -3
  50. package/dist/src/entities/agent-sessions/agent-session.d.ts +209 -22
  51. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  52. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  53. package/dist/src/entities/agent-sessions/namespace.d.ts +72 -16
  54. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  55. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  56. package/dist/src/entities/agent-sessions/review.d.ts +56 -5
  57. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  58. package/dist/src/entities/agents/agent.d.ts +98 -3
  59. package/dist/src/entities/agents/namespace.d.ts +52 -8
  60. package/dist/src/entities/ai/namespace.d.ts +10 -2
  61. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  62. package/dist/src/entities/api-keys/namespace.d.ts +18 -3
  63. package/dist/src/entities/bots/bot.d.ts +44 -9
  64. package/dist/src/entities/bots/namespace.d.ts +13 -1
  65. package/dist/src/entities/bots/token.d.ts +6 -1
  66. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  67. package/dist/src/entities/calendar/booking-namespace.d.ts +14 -1
  68. package/dist/src/entities/calendar/booking.d.ts +15 -0
  69. package/dist/src/entities/calendar/calendar.d.ts +10 -3
  70. package/dist/src/entities/calendar/event.d.ts +68 -9
  71. package/dist/src/entities/calendar/namespace.d.ts +91 -12
  72. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  73. package/dist/src/entities/calls/call-record.d.ts +107 -17
  74. package/dist/src/entities/calls/connection.d.ts +7 -1
  75. package/dist/src/entities/calls/message.d.ts +27 -5
  76. package/dist/src/entities/calls/namespace.d.ts +15 -3
  77. package/dist/src/entities/canvases/canvas.d.ts +329 -0
  78. package/dist/src/entities/channels/access-request.d.ts +10 -2
  79. package/dist/src/entities/channels/activity.d.ts +20 -4
  80. package/dist/src/entities/channels/channel.d.ts +154 -27
  81. package/dist/src/entities/channels/labels.d.ts +41 -7
  82. package/dist/src/entities/channels/message.d.ts +105 -8
  83. package/dist/src/entities/channels/message.test.d.ts +1 -0
  84. package/dist/src/entities/channels/namespace.d.ts +37 -7
  85. package/dist/src/entities/channels/post.d.ts +13 -7
  86. package/dist/src/entities/channels/post.test.d.ts +1 -0
  87. package/dist/src/entities/channels/share.d.ts +9 -0
  88. package/dist/src/entities/channels/share.test.d.ts +1 -0
  89. package/dist/src/entities/channels/thread.d.ts +24 -4
  90. package/dist/src/entities/chats/chat.d.ts +57 -7
  91. package/dist/src/entities/chats/generation.d.ts +11 -2
  92. package/dist/src/entities/chats/namespace.d.ts +10 -2
  93. package/dist/src/entities/connected-apps/connected-app.d.ts +16 -2
  94. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  95. package/dist/src/entities/connected-apps/namespace.d.ts +18 -0
  96. package/dist/src/entities/crm/company.d.ts +64 -16
  97. package/dist/src/entities/crm/contact.d.ts +102 -14
  98. package/dist/src/entities/crm/namespace.d.ts +113 -22
  99. package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
  100. package/dist/src/entities/crm/pipeline.d.ts +292 -29
  101. package/dist/src/entities/crm/pipelines.d.ts +69 -4
  102. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  103. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  104. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  105. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  106. package/dist/src/entities/databases/column.d.ts +54 -7
  107. package/dist/src/entities/databases/database.d.ts +160 -18
  108. package/dist/src/entities/databases/namespace.d.ts +40 -8
  109. package/dist/src/entities/databases/row.d.ts +2 -0
  110. package/dist/src/entities/databases/saved-query.d.ts +151 -0
  111. package/dist/src/entities/databases/table.d.ts +73 -10
  112. package/dist/src/entities/databases/view.d.ts +37 -5
  113. package/dist/src/entities/databases/webhook.d.ts +8 -1
  114. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  115. package/dist/src/entities/documents/anchor.d.ts +12 -2
  116. package/dist/src/entities/documents/comment.d.ts +29 -5
  117. package/dist/src/entities/documents/create.test.d.ts +1 -0
  118. package/dist/src/entities/documents/document.d.ts +284 -26
  119. package/dist/src/entities/documents/markdown.d.ts +25 -0
  120. package/dist/src/entities/documents/namespace.d.ts +146 -13
  121. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  122. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  123. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  124. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  125. package/dist/src/entities/documents/version.d.ts +5 -1
  126. package/dist/src/entities/email/attachment.d.ts +3 -0
  127. package/dist/src/entities/email/draft.d.ts +61 -9
  128. package/dist/src/entities/email/filter.d.ts +12 -2
  129. package/dist/src/entities/email/label.d.ts +7 -1
  130. package/dist/src/entities/email/link.d.ts +5 -1
  131. package/dist/src/entities/email/message.d.ts +72 -14
  132. package/dist/src/entities/email/namespace.d.ts +134 -24
  133. package/dist/src/entities/email/thread.d.ts +124 -18
  134. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  135. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  136. package/dist/src/entities/entity.d.ts +65 -6
  137. package/dist/src/entities/external-chat/chat.d.ts +80 -12
  138. package/dist/src/entities/external-chat/message.d.ts +1 -1
  139. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  140. package/dist/src/entities/external-chat/send.d.ts +10 -2
  141. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  142. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  143. package/dist/src/entities/foreign/namespace.d.ts +5 -1
  144. package/dist/src/entities/forms/form.d.ts +91 -14
  145. package/dist/src/entities/forms/namespace.d.ts +10 -2
  146. package/dist/src/entities/forms/question.d.ts +35 -7
  147. package/dist/src/entities/forms/response.d.ts +25 -5
  148. package/dist/src/entities/forms/section.d.ts +15 -3
  149. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  150. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  151. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  152. package/dist/src/entities/harnesses/namespace.d.ts +54 -8
  153. package/dist/src/entities/harnesses/pairing.d.ts +13 -2
  154. package/dist/src/entities/images/image.d.ts +16 -5
  155. package/dist/src/entities/images/namespace.d.ts +8 -1
  156. package/dist/src/entities/imports/entry.d.ts +65 -0
  157. package/dist/src/entities/imports/namespace.d.ts +103 -0
  158. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  159. package/dist/src/entities/initiatives/initiative.d.ts +128 -4
  160. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  161. package/dist/src/entities/initiatives/namespace.d.ts +71 -7
  162. package/dist/src/entities/me/namespace.d.ts +28 -3
  163. package/dist/src/entities/meetings/meeting.d.ts +46 -8
  164. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  165. package/dist/src/entities/memory/namespace.d.ts +49 -0
  166. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  167. package/dist/src/entities/messages/discussion.d.ts +84 -0
  168. package/dist/src/entities/messages/thread.d.ts +19 -5
  169. package/dist/src/entities/notifications/namespace.d.ts +41 -7
  170. package/dist/src/entities/notifications/notification.d.ts +31 -6
  171. package/dist/src/entities/passwords/item.d.ts +118 -0
  172. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  173. package/dist/src/entities/pins/namespace.d.ts +23 -4
  174. package/dist/src/entities/projects/namespace.d.ts +29 -0
  175. package/dist/src/entities/projects/project.d.ts +58 -7
  176. package/dist/src/entities/properties/namespace.d.ts +67 -11
  177. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  178. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  179. package/dist/src/entities/properties/property-option.d.ts +14 -2
  180. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  181. package/dist/src/entities/routines/namespace.d.ts +198 -14
  182. package/dist/src/entities/routines/routine.d.ts +174 -27
  183. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  184. package/dist/src/entities/saved-views/namespace.d.ts +58 -0
  185. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  186. package/dist/src/entities/search/exclusions.d.ts +6 -0
  187. package/dist/src/entities/search/namespace.d.ts +9 -3
  188. package/dist/src/entities/search/options.d.ts +3 -2
  189. package/dist/src/entities/sharing/access.d.ts +50 -9
  190. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  191. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  192. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  193. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  194. package/dist/src/entities/tasks/namespace.d.ts +18 -5
  195. package/dist/src/entities/tasks/task.d.ts +21 -3
  196. package/dist/src/entities/teams/invite.d.ts +3 -0
  197. package/dist/src/entities/teams/namespace.d.ts +10 -2
  198. package/dist/src/entities/teams/team.d.ts +22 -2
  199. package/dist/src/entities/ui/app-link.d.ts +24 -0
  200. package/dist/src/entities/ui/namespace.d.ts +75 -0
  201. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  202. package/dist/src/entities/users/namespace.d.ts +26 -4
  203. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  204. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  205. package/dist/src/entities/users/user.d.ts +52 -1
  206. package/dist/src/entities/web/namespace.d.ts +6 -0
  207. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  208. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  209. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  210. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  211. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  212. package/dist/src/entities/workspace/namespace.d.ts +12 -4
  213. package/dist/src/entities/workspace/query.d.ts +5 -1
  214. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  215. package/dist/src/events/hydrate/document.d.ts +5 -0
  216. package/dist/src/events/hydrate/user.d.ts +14 -0
  217. package/dist/src/events/receiver.d.ts +2 -0
  218. package/dist/src/events/types.d.ts +2 -1
  219. package/dist/src/macro.d.ts +59 -6
  220. package/dist/src/macro.js +18710 -10355
  221. package/dist/src/utils/activity.d.ts +2 -0
  222. package/dist/src/utils/index.d.ts +1 -1
  223. package/dist/src/utils/lazy.d.ts +20 -1
  224. package/dist/src/utils/options.d.ts +7 -0
  225. package/dist/src/utils/pagination.d.ts +16 -0
  226. package/dist/src/utils/verbs.d.ts +3 -0
  227. package/package.json +1 -1
  228. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -1,6 +1,6 @@
1
1
  import type { AgentMode, AutoArchivePreferencesBody, CodingPreferencesBody, SandboxSize } from '../../../generated/agent-harness/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
- import { AgentSession, type CreateManagedSessionOptions, type RegisteredWork, type SelectableRepository } from './agent-session';
3
+ import { AgentSession, type AgentSessionUpdates, type CreateManagedSessionOptions, type RegisteredWork, type SelectableRepository } from './agent-session';
4
4
  /**
5
5
  * Entry point for coding-agent sessions.
6
6
  *
@@ -11,16 +11,15 @@ import { AgentSession, type CreateManagedSessionOptions, type RegisteredWork, ty
11
11
  *
12
12
  * Do repository and coding work yourself when you can. Start another agent session only when the user asks for one, or the work needs a repository runtime you do not have.
13
13
  *
14
- * Start sessions from ExecuteCode. macro.agents.list() returns the user's own configurable agents; choose by name and instructions, preferring an agent the user named, and pass it as `agent` to macro.agentSessions.createManaged. Never invent an agent or construct one by id. To use the default persona instead, omit `agent`. Read AgentSessionNamespace.createManaged with ReadCodeDocs before the first call.
14
+ * Start sessions from ExecuteCode. For coding work, macro.agents.coding() lists the coding personas the user can start right now, built-in ones such as Cursor included; for a chat agent, macro.agents.list() lists the user's configurable agents. Choose by name, description and instructions, preferring an agent the user named, and pass its `agent` handle to macro.agentSessions.createManaged. Never invent an agent or construct one by id. To use Macro's default persona instead, omit `agent`. Read AgentSessionNamespace.createManaged with ReadCodeDocs before the first call.
15
15
  *
16
16
  * ```javascript
17
17
  * export async function main({macro}) {
18
- * const agents = await macro.agents.list();
19
- * const names = await Promise.all(agents.map((agent) => agent.name()));
20
- * const agent = agents[names.indexOf('Web maintainer')];
21
- * if (!agent) return {data: {error: 'No agent named Web maintainer', available: names}};
18
+ * const coding = await macro.agents.coding();
19
+ * const chosen = coding.find((option) => option.name === 'Cursor');
20
+ * if (!chosen) return {data: {error: 'Cursor is not connected', available: coding.map((option) => option.name)}};
22
21
  * const session = await macro.agentSessions.createManaged({
23
- * agent,
22
+ * agent: chosen.agent,
24
23
  * repoUrl: 'https://github.com/acme/web',
25
24
  * prompt: 'Fix the login redirect loop in acme/web. ...',
26
25
  * });
@@ -29,6 +28,10 @@ import { AgentSession, type CreateManagedSessionOptions, type RegisteredWork, ty
29
28
  * ```
30
29
  *
31
30
  * The prompt must be self-contained: the task, repository, relevant findings and links, constraints, and expected outcome. The new session does not receive this conversation. When the outcome is a pull request, require it to be ready for review, not a draft, with CI passing before the agent finishes. Create once per task and do not retry automatically after an uncertain failure. Link the session in your reply with its id. To check on it later, create a routine; never wait or poll inside an execution.
31
+ *
32
+ * ## Sessions waiting for the user
33
+ *
34
+ * macro.agentSessions.updates() lists the user's sessions waiting on them (permission requests, questions, held tool approvals) or stalled. The user answers them only on cards: in ExecuteCode, whenever it returns items, present them with execution.views.present({widgets: [{type: "agentUpdates", items: updates.items}]}). A session's held tool calls come from session.pendingApprovals(); approve or deny one only when the user said so for that call. session.linkTask(task) links a session the user owns to its Macro task, and the session's pull request with it.
32
35
  */
33
36
  export declare class AgentSessionNamespace {
34
37
  private readonly client;
@@ -37,50 +40,103 @@ export declare class AgentSessionNamespace {
37
40
  byId(id: string): AgentSession;
38
41
  /**
39
42
  * Create a managed session as `agent` when one is named, otherwise the
40
- * deployment's default coding persona. List personas with
41
- * {@link AgentNamespace.list} and construct one with {@link Agent.byId}.
42
- * Unknown or inaccessible personas fail. `model` and `instructions`
43
+ * deployment's default persona. Take `agent` from
44
+ * {@link AgentNamespace.coding} (coding personas, Cursor included) or
45
+ * {@link AgentNamespace.list} (configurable agents); never construct one
46
+ * from an id. Unknown or inaccessible personas fail. `model` and `instructions`
43
47
  * outrank the persona's. `repoUrl` is honored for Cursor; omit `agent`
44
48
  * and it starts as Cursor.
49
+ *
50
+ * @write
51
+ * @openworld
45
52
  */
46
53
  createManaged(opts?: CreateManagedSessionOptions): Promise<AgentSession>;
47
54
  /**
48
55
  * The sessions the caller registered as its work with
49
56
  * {@link AgentSession.registerAsWork} and can still view, newest first.
50
57
  * Ended registrations and archived sessions are left out.
58
+ *
59
+ * @readonly
51
60
  */
52
61
  registeredWork(): Promise<RegisteredWork[]>;
53
62
  /**
54
63
  * Whether `prompt` needs a chat agent (`'chat'`) or a coding agent
55
64
  * (`'code'`), as the app's Auto mode decides before starting a session.
65
+ *
66
+ * @write
56
67
  */
57
68
  chooseMode(prompt: string): Promise<AgentMode>;
58
69
  /**
59
70
  * The GitHub repositories the caller can hand a managed session, with the
60
71
  * branch each one's sessions start on by default.
72
+ *
73
+ * @readonly
74
+ * @openworld
61
75
  */
62
76
  repositories(): Promise<SelectableRepository[]>;
63
77
  /**
64
78
  * Branch names on one repository the caller can start a managed session
65
79
  * from. `repoUrl` is one of the URLs {@link AgentSessionNamespace.repositories}
66
80
  * lists.
81
+ *
82
+ * @readonly
83
+ * @openworld
67
84
  */
68
85
  repositoryBranches(repoUrl: string): Promise<string[]>;
86
+ /**
87
+ * List coding sessions awaiting the caller or stalled over 20 minutes.
88
+ *
89
+ * Includes permission requests, questions and held tool approvals to
90
+ * answer, and stalled sessions, newest activity first. Read a session's held approvals
91
+ * with {@link AgentSession.pendingApprovals}.
92
+ *
93
+ * @readonly
94
+ */
95
+ updates(): Promise<AgentSessionUpdates>;
69
96
  /**
70
97
  * The sessions linked to the GitHub pull request at `url` that the caller
71
98
  * can view.
99
+ *
100
+ * @readonly
72
101
  */
73
102
  forPullRequest(url: string): Promise<AgentSession[]>;
74
- /** The caller's default sandbox size for new `@coder` sessions. */
103
+ /**
104
+ * The caller's default sandbox size for new `@coder` sessions.
105
+ *
106
+ * @readonly
107
+ */
75
108
  defaultSandboxSize(): Promise<SandboxSize>;
76
- /** Set the caller's default sandbox size for the next `@coder` mention. */
109
+ /**
110
+ * Set the caller's default sandbox size for the next `@coder` mention.
111
+ *
112
+ * @write
113
+ * @idempotent
114
+ */
77
115
  setDefaultSandboxSize(size: SandboxSize): Promise<SandboxSize>;
78
- /** What the caller's new coding sessions are told to do beyond their assignment. */
116
+ /**
117
+ * What the caller's new coding sessions are told to do beyond their assignment.
118
+ *
119
+ * @readonly
120
+ */
79
121
  codingPreferences(): Promise<CodingPreferencesBody>;
80
- /** Which triggers archive the caller's sessions by default; each is off unless chosen. */
122
+ /**
123
+ * Which triggers archive the caller's sessions by default; each is off unless chosen.
124
+ *
125
+ * @readonly
126
+ */
81
127
  autoArchivePreferences(): Promise<AutoArchivePreferencesBody>;
82
- /** Replace which triggers archive the caller's sessions by default. */
128
+ /**
129
+ * Replace which triggers archive the caller's sessions by default.
130
+ *
131
+ * @write
132
+ * @idempotent
133
+ */
83
134
  setAutoArchivePreferences(preferences: AutoArchivePreferencesBody): Promise<AutoArchivePreferencesBody>;
84
- /** Replace the caller's coding preferences. */
135
+ /**
136
+ * Replace the caller's coding preferences.
137
+ *
138
+ * @write
139
+ * @idempotent
140
+ */
85
141
  setCodingPreferences(preferences: CodingPreferencesBody): Promise<CodingPreferencesBody>;
86
142
  }
@@ -67,7 +67,7 @@ export type SessionOrigin =
67
67
  task: Task;
68
68
  project: Initiative;
69
69
  }
70
- /** A person opened the session directly, from the composer. */
70
+ /** A person opened the session directly: from the composer, or by asking for a routine draft. */
71
71
  | {
72
72
  kind: 'requested';
73
73
  by: User;
@@ -8,8 +8,10 @@ import type { MacroClient } from '../../utils/client';
8
8
  *
9
9
  * List-sourced only - there is no per-action GET, only the queue snapshot -
10
10
  * so this wraps whatever DTO the caller already has, the same shape
11
- * `CrmComment` wraps a list-sourced record, rather than `MacroEntity`'s
11
+ * `DiscussionComment` wraps a list-sourced record, rather than `MacroEntity`'s
12
12
  * lazy-fetch-by-id.
13
+ *
14
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
13
15
  */
14
16
  export declare class QueuedAction {
15
17
  private readonly client;
@@ -37,10 +39,22 @@ export declare class QueuedAction {
37
39
  * Replace this queued prompt's text before it dispatches. Returns this
38
40
  * handle for chaining; the edit endpoint answers 204, so `prompt` is
39
41
  * applied locally rather than reread from a response body.
42
+ *
43
+ * @write
44
+ * @idempotent
40
45
  */
41
46
  edit(prompt: string): Promise<this>;
42
- /** Move this action to the front and interrupt the current turn to run it next. */
47
+ /**
48
+ * Move this action to the front and interrupt the current turn to run it next.
49
+ *
50
+ * @destructive
51
+ */
43
52
  steer(): Promise<void>;
44
- /** Remove this action from the queue before it dispatches. */
53
+ /**
54
+ * Remove this action from the queue before it dispatches.
55
+ *
56
+ * @destructive
57
+ * @idempotent
58
+ */
45
59
  remove(): Promise<void>;
46
60
  }
@@ -16,22 +16,56 @@ export declare class SessionReview extends MacroEntity<ReviewRecord> {
16
16
  static list(client: MacroClient, execution: CodeExecution): Promise<SessionReview[]>;
17
17
  protected fetch(): Promise<ReviewRecord>;
18
18
  readonly title: () => Promise<string>;
19
- readonly kind: () => Promise<"email" | "calendar" | "import">;
19
+ readonly kind: () => Promise<"calendar" | "email" | "import">;
20
+ /**
21
+ * The session this review belongs to.
22
+ *
23
+ * @readonly
24
+ */
20
25
  session(): AgentSession;
21
- /** Compact reference for main()'s returned reviews array. */
26
+ /**
27
+ * Compact reference for main()'s returned reviews array.
28
+ *
29
+ * @readonly
30
+ */
22
31
  reference(): Promise<{
23
32
  kind: ReviewRecord['kind'];
24
33
  id: string;
25
34
  }>;
35
+ /**
36
+ * The review's items, each with its draft, status and result.
37
+ *
38
+ * @readonly
39
+ */
26
40
  items(): Promise<ReviewItem[]>;
41
+ /**
42
+ * Reload the saved review, for example after a decision or a conflict.
43
+ *
44
+ * @readonly
45
+ */
27
46
  refresh(): Promise<this>;
28
- /** Submit the saved pending drafts. Never retries a conflict or ambiguous send. */
47
+ /**
48
+ * Submit the saved pending drafts. Never retries a conflict or ambiguous send.
49
+ *
50
+ * @destructive
51
+ * @openworld
52
+ */
29
53
  submitAll(): Promise<void>;
54
+ /**
55
+ * Dismiss every pending draft without sending it.
56
+ *
57
+ * @destructive
58
+ * @idempotent
59
+ */
30
60
  dismissAll(): Promise<void>;
31
61
  /** @internal Handles attach the cached revision; callers must refresh after a conflict. */
32
62
  private decide;
33
63
  }
34
- /** An item handle scopes edits and decisions to its persisted review. */
64
+ /**
65
+ * An item handle scopes edits and decisions to its persisted review.
66
+ *
67
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
68
+ */
35
69
  export declare class ReviewItem {
36
70
  private readonly snapshot;
37
71
  private readonly actions;
@@ -45,9 +79,26 @@ export declare class ReviewItem {
45
79
  get draft(): ReviewRecord['items'][number]['draft'];
46
80
  /** The action's confirmed response, `null` until it completes. */
47
81
  get result(): ReviewRecord['items'][number]['result'];
48
- /** Replace this pending draft; `kind` must match the review's. */
82
+ /**
83
+ * Replace this pending draft; `kind` must match the review's.
84
+ *
85
+ * @write
86
+ * @idempotent
87
+ */
49
88
  edit(draft: ReviewDraft): Promise<void>;
89
+ /**
90
+ * Submit this pending draft, sending the email or creating the event it holds.
91
+ *
92
+ * @destructive
93
+ * @openworld
94
+ */
50
95
  submit(): Promise<void>;
96
+ /**
97
+ * Dismiss this pending draft without sending it.
98
+ *
99
+ * @destructive
100
+ * @idempotent
101
+ */
51
102
  dismiss(): Promise<void>;
52
103
  }
53
104
  /** A replacement draft keyed by its review's kind. */
@@ -11,7 +11,11 @@ export declare class ToolApproval {
11
11
  private constructor();
12
12
  /** Construct a scoped approval handle. */
13
13
  static byId(client: MacroClient, session: AgentSession, id: string): ToolApproval;
14
- /** Answer the approval using the generated discriminated answer contract. */
14
+ /**
15
+ * Answer the approval using the generated discriminated answer contract.
16
+ *
17
+ * @write
18
+ */
15
19
  answer(answer: AnswerToolApprovalRequest['answer']): Promise<import("../../../generated/agent-harness").AnswerToolApprovalResponse>;
16
20
  /** Serialize scoped identity only. */
17
21
  toJSON(): {
@@ -4,6 +4,38 @@ import { Channel } from '../channels/channel';
4
4
  import { MacroEntity } from '../entity';
5
5
  import { Harness } from '../harnesses/harness';
6
6
  import type { Team } from '../teams/team';
7
+ /**
8
+ * The settings {@link Agent.update} changes; each one left out keeps its
9
+ * current value.
10
+ */
11
+ export type AgentPatch = {
12
+ /** New instructions, whole. */
13
+ instructions?: string;
14
+ /**
15
+ * New runtime: `in-memory`, `cursor`, or `macrod` with the registered
16
+ * `host` that serves it. The current model may not exist on the new
17
+ * runtime, so usually pass `defaultModel` with it.
18
+ */
19
+ runtime?: {
20
+ harness: string;
21
+ host?: Harness;
22
+ };
23
+ /** New default model, as the runtime names it. */
24
+ defaultModel?: string;
25
+ /** Mentionable in every channel, or only in `channels`. */
26
+ channels?: {
27
+ scope: 'all';
28
+ } | {
29
+ scope: 'selected';
30
+ channels: Channel[];
31
+ };
32
+ /** The connected apps its sessions are handed. */
33
+ apps?: AgentApps;
34
+ /** Approve tool permission requests without asking, where the runtime allows it. */
35
+ autoAcceptPermissions?: boolean;
36
+ /** A coding agent (`true`) or a chat agent (`false`). */
37
+ isCoding?: boolean;
38
+ };
7
39
  /** Agent creation and replacement settings. */
8
40
  export type AgentOptions = Omit<CreateAgentRequest, 'channel_ids' | 'team_id' | 'harness_id' | 'auto_accept_permissions' | 'avatar_url' | 'channel_scope' | 'default_model' | 'is_coding'> & {
9
41
  /** Channels the agent can access. */
@@ -23,7 +55,27 @@ export type AgentOptions = Omit<CreateAgentRequest, 'channel_ids' | 'team_id' |
23
55
  /** Whether this is a coding agent. */
24
56
  isCoding: boolean;
25
57
  };
26
- /** A configurable agent backed by a bot identity. */
58
+ /** The connected apps an agent's sessions are handed. */
59
+ export type AgentApps = {
60
+ /** Whatever apps the person running the session has connected. */
61
+ scope: 'owner_connections';
62
+ } | {
63
+ /** Exactly `servers`. */
64
+ scope: 'selected';
65
+ /** The apps, in the order the agent's author picked them. */
66
+ servers: {
67
+ /** Pipedream app slug, e.g. `linear`. */
68
+ appSlug: string;
69
+ /** Display name, e.g. `Linear`. */
70
+ name: string;
71
+ }[];
72
+ };
73
+ /**
74
+ * An agent persona backed by a bot identity. Its settings load from
75
+ * {@link AgentNamespace.list}, so they exist only for configurable agents;
76
+ * built-in personas such as Cursor have none, and are listed with
77
+ * {@link AgentNamespace.coding}.
78
+ */
27
79
  export declare class Agent extends MacroEntity<AgentRecord> {
28
80
  /** Construct a lazy agent handle. */
29
81
  static byId(client: MacroClient, id: string): Agent;
@@ -32,6 +84,31 @@ export declare class Agent extends MacroEntity<AgentRecord> {
32
84
  protected fetch(): Promise<AgentRecord>;
33
85
  /** Display name. */
34
86
  readonly name: () => Promise<string>;
87
+ /** Handle people `@` mention it by. */
88
+ readonly handle: () => Promise<string>;
89
+ /** What the agent is for, when its author said. */
90
+ readonly description: () => Promise<string | undefined>;
91
+ /**
92
+ * Runtime its sessions run on: `in-memory` (Macro), `cursor`,
93
+ * `codex-cloud`, or `macrod` (a registered machine, named by
94
+ * {@link Agent.host}).
95
+ */
96
+ readonly harness: () => Promise<string>;
97
+ /**
98
+ * Whether it is a coding agent, which works in a repository and answers a
99
+ * mention with a live session, rather than a chat agent replying in the
100
+ * thread.
101
+ */
102
+ readonly isCoding: () => Promise<boolean>;
103
+ /**
104
+ * Whether its sessions approve tool permission requests without asking,
105
+ * where the runtime allows it.
106
+ */
107
+ readonly autoAcceptPermissions: () => Promise<NonNullable<boolean | null | undefined>>;
108
+ /** `all`: mentionable everywhere; `selected`: only in {@link Agent.channels}. */
109
+ readonly channelScope: () => Promise<import("../../../generated/storage").AgentChannelScope>;
110
+ /** The connected apps its sessions are handed. */
111
+ readonly apps: () => Promise<AgentApps>;
35
112
  /** Agent instructions. */
36
113
  readonly instructions: () => Promise<string>;
37
114
  /** Default model. */
@@ -40,8 +117,26 @@ export declare class Agent extends MacroEntity<AgentRecord> {
40
117
  readonly channels: () => Promise<Channel[]>;
41
118
  /** Host running this agent. */
42
119
  readonly host: () => Promise<Harness | undefined>;
43
- /** Replace agent settings. */
44
- update(options: AgentOptions): Promise<void>;
120
+ /**
121
+ * Change only the settings in `patch`; every setting left out keeps its
122
+ * current value. Instructions, channel and app lists are replaced whole:
123
+ * to edit one, apply your change to the current value and pass the result.
124
+ * Changes apply to sessions opened afterwards. Built-in personas cannot be
125
+ * updated.
126
+ *
127
+ * @write
128
+ * @idempotent
129
+ */
130
+ update(patch: AgentPatch): Promise<void>;
131
+ /**
132
+ * Replace every setting, including the name, handle and owning team:
133
+ * fields left out of `options` return to their defaults. Use
134
+ * {@link Agent.update} to change some settings and keep the rest.
135
+ *
136
+ * @destructive
137
+ * @idempotent
138
+ */
139
+ replace(options: AgentOptions): Promise<void>;
45
140
  }
46
141
  /** Convert entity references into the generated agent request. */
47
142
  export declare function agentBody(options: AgentOptions): CreateAgentRequest;
@@ -1,22 +1,66 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Agent, type AgentOptions } from './agent';
3
3
  /**
4
- * Configurable agents.
4
+ * A coding agent the caller can start a session as right now: a built-in
5
+ * persona such as Cursor once its runtime is connected, or one of their
6
+ * configured coding agents whose runtime is reachable.
7
+ */
8
+ export type CodingAgent = {
9
+ /** Pass as `agent` to {@link AgentSessionNamespace.createManaged}. */
10
+ agent: Agent;
11
+ /** Display name. */
12
+ name: string;
13
+ /** What the persona is for, when known. */
14
+ description: string | undefined;
15
+ /** Saved guidance on its repositories and specialties; empty for built-ins. */
16
+ instructions: string;
17
+ /** Runtime its sessions run on, e.g. `cursor` or `macrod`. */
18
+ harness: string;
19
+ /** Default model, absent when the runtime chooses. */
20
+ model: string | undefined;
21
+ };
22
+ /**
23
+ * Agent personas: the built-in ones Macro ships and the agents the user configures.
5
24
  *
6
- * @routing Use when the user wants to change how one of their Macro agent personas is set up: its instructions, model, runtime, channels or hosts; not any request the user asks you, the agent, to carry out.
25
+ * @routing Use when the user wants to pick, read or change one of their Macro agent personas: its instructions, model, runtime, channels, apps or hosts; not any request the user asks you, the agent, to carry out.
7
26
  */
8
27
  export declare class AgentNamespace {
9
28
  private readonly client;
10
29
  constructor(client: MacroClient);
11
- /** Construct a lazy agent handle. */
30
+ /**
31
+ * A lazy handle to a configurable agent. Get handles from
32
+ * {@link AgentNamespace.list} or {@link AgentNamespace.coding} instead of
33
+ * constructing one from an id.
34
+ */
12
35
  byId(id: string): Agent;
13
36
  /**
14
- * Accessible custom agents. Pass one to
15
- * {@link AgentSessionNamespace.createManaged} to start a session as that
16
- * persona. System personas such as Cursor are constructed with
17
- * {@link Agent.byId}.
37
+ * The configurable agents the user can manage (their own, their teams', and
38
+ * channel agents they can mention), coding and chat, with their full
39
+ * settings. Built-in personas such as Cursor are not here; list those with
40
+ * {@link AgentNamespace.coding}. Pass one as `agent` to
41
+ * {@link AgentSessionNamespace.createManaged} to start a session as it.
42
+ *
43
+ * @readonly
18
44
  */
19
45
  list(): Promise<Agent[]>;
20
- /** Create an agent. */
46
+ /**
47
+ * Choose a coding agent from this list before delegating coding work: the
48
+ * coding personas the user can start a session as right now, built-in ones
49
+ * such as Cursor first, then their configured coding agents whose runtime
50
+ * is connected. Prefer the agent the user named, otherwise the one whose
51
+ * name, description, instructions and runtime best fit the repository and
52
+ * task, and pass its `agent` to {@link AgentSessionNamespace.createManaged}.
53
+ * Empty when nothing is connected; tell the user to connect Cursor or
54
+ * configure a coding agent. Macro's own default persona is not listed:
55
+ * omit `agent` to use it.
56
+ *
57
+ * @readonly
58
+ */
59
+ coding(): Promise<CodingAgent[]>;
60
+ /**
61
+ * Create an agent.
62
+ *
63
+ * @write
64
+ */
21
65
  create(options: AgentOptions): Promise<Agent>;
22
66
  }
@@ -5,11 +5,15 @@ export type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, St
5
5
  /**
6
6
  * Shared cognition endpoints, charged to the authenticated acting user.
7
7
  *
8
- * @routing Use when generating structured objects or classifying supplied content with Jev; not generating images (`macro.images`) or answering the user yourself.
8
+ * @routing Use when asking a model to answer named yes/no questions or fill a JSON Schema from content you supply, or when reading AI usage; not generating images (`macro.images`) or answering the user yourself.
9
9
  */
10
10
  export declare class AiNamespace {
11
11
  private readonly client;
12
- /** Read AI usage over a time range, optionally restricting it to users. */
12
+ /**
13
+ * Read AI usage over a time range, optionally restricting it to users.
14
+ *
15
+ * @readonly
16
+ */
13
17
  usage(options?: Omit<UsageRequest, 'include_users'> & {
14
18
  users?: User[];
15
19
  }): Promise<import("../../../generated/cognition").UsageSummary>;
@@ -18,11 +22,15 @@ export declare class AiNamespace {
18
22
  * Generate an answer matching a JSON Schema. Set toolset to { type: 'none' }
19
23
  * to use only supplied context. Other toolsets can perform the requested
20
24
  * actions; always inspect outcome and toolActivity, including interruptions.
25
+ *
26
+ * @write
21
27
  */
22
28
  structuredCompletion(request: StructuredCompletionRequest): Promise<StructuredCompletionResponse>;
23
29
  /**
24
30
  * Ask named yes/no questions about JSON input. Each probability estimates
25
31
  * yes, from 0 to 1. This classifies supplied data without running tools.
32
+ *
33
+ * @readonly
26
34
  */
27
35
  decide(request: DecisionRequest): Promise<DecisionResponse>;
28
36
  }
@@ -12,6 +12,11 @@ export declare class UserApiKey extends MacroEntity<UserApiKeyInfo> {
12
12
  readonly name: () => Promise<string>;
13
13
  /** Creation time. */
14
14
  readonly createdAt: () => Promise<string>;
15
- /** Revoke this key. */
15
+ /**
16
+ * Revoke this key.
17
+ *
18
+ * @destructive
19
+ * @idempotent
20
+ */
16
21
  delete(): Promise<void>;
17
22
  }
@@ -10,13 +10,28 @@ export declare class ApiKeyNamespace {
10
10
  constructor(client: MacroClient);
11
11
  /** Construct a lazy key handle. */
12
12
  byId(id: string): UserApiKey;
13
- /** List metadata for the caller's API keys. */
13
+ /**
14
+ * List metadata for the caller's API keys.
15
+ *
16
+ * @readonly
17
+ */
14
18
  list(): Promise<UserApiKey[]>;
15
- /** Create a key. Save the secret now; it cannot be retrieved later. */
19
+ /**
20
+ * Create a key; refused to an agent's program (ExecuteCode, a routine), so
21
+ * there have the user create one in Macro's settings. Save the secret now;
22
+ * it cannot be retrieved later.
23
+ *
24
+ * @write
25
+ */
16
26
  create(name: string): Promise<{
17
27
  key: UserApiKey;
18
28
  secret: string;
19
29
  }>;
20
- /** Exchange an email address for a Macro API token, subject to server authorization. */
30
+ /**
31
+ * Exchange an email address for a Macro API token, subject to server
32
+ * authorization; refused to an agent's program (ExecuteCode, a routine).
33
+ *
34
+ * @write
35
+ */
21
36
  tokenForEmail(email: string): Promise<import("../../../generated/auth").MacroApiTokenResponse>;
22
37
  }
@@ -75,28 +75,63 @@ export declare class Bot extends MacroEntity<BotRecord> {
75
75
  readonly updatedAt: () => Promise<string>;
76
76
  /** The owning user or team. */
77
77
  readonly owner: () => Promise<BotOwner | undefined>;
78
- /** Change the bot's profile; pass only the fields that should change. */
78
+ /**
79
+ * Change the bot's profile; pass only the fields that should change.
80
+ *
81
+ * @write
82
+ * @idempotent
83
+ */
79
84
  update(changes: UpdateBotOptions): Promise<void>;
80
- /** Delete the bot. Its tokens stop working and it leaves every channel. */
85
+ /**
86
+ * Delete the bot. Its tokens stop working and it leaves every channel.
87
+ *
88
+ * @destructive
89
+ * @idempotent
90
+ */
81
91
  delete(): Promise<void>;
82
- /** Channels the bot can post to. */
92
+ /**
93
+ * Channels the bot can post to.
94
+ *
95
+ * @readonly
96
+ */
83
97
  channels(): Promise<Channel[]>;
84
98
  /**
85
99
  * One webhook per channel the bot can post to. POST JSON `{ content }` with
86
100
  * a token from {@link createToken} in the `x-macro-bot-token` header and
87
101
  * `x-macro-bot-scope: user`. Empty until {@link grantChannel}.
102
+ *
103
+ * @readonly
88
104
  */
89
105
  webhooks(): Promise<BotWebhook[]>;
90
- /** Let the bot post to a channel. The caller must be a member of it and manage the bot. */
106
+ /**
107
+ * Let the bot post to a channel. The caller must be a member of it and manage the bot.
108
+ *
109
+ * @write
110
+ * @idempotent
111
+ */
91
112
  grantChannel(channel: Channel): Promise<void>;
92
- /** Remove the bot from a channel. Works after the caller has left the channel. */
113
+ /**
114
+ * Remove the bot from a channel. Works after the caller has left the channel.
115
+ *
116
+ * @destructive
117
+ * @idempotent
118
+ */
93
119
  revokeChannel(channel: Channel): Promise<void>;
94
- /** The bot's tokens, including revoked and expired ones. Secrets are never returned. */
120
+ /**
121
+ * The bot's tokens, including revoked and expired ones. Secrets are never returned.
122
+ *
123
+ * @readonly
124
+ */
95
125
  tokens(): Promise<BotToken[]>;
96
126
  /**
97
- * Mint a bearer token for the bot's webhooks and API. The secret is returned
98
- * once and cannot be read again; never write it into chat, documents or
99
- * results. To hand a user a token, have them mint it in bot settings.
127
+ * Mint a bearer token for the bot's webhooks and API; refused to an agent's
128
+ * program (ExecuteCode, a routine), so there present a card that mints it,
129
+ * `execution.views.present({widgets: [{type: 'botCredential', botId}]})` in
130
+ * an agent session, or have the user mint it in bot settings. The secret is
131
+ * returned once and cannot be read again; never write it into chat,
132
+ * documents or results.
133
+ *
134
+ * @write
100
135
  */
101
136
  createToken(options?: {
102
137
  label?: string;