@macro-inc/sdk 0.4.1 → 0.5.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 (185) hide show
  1. package/README.md +169 -7
  2. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  4. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  5. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  6. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  7. package/dist/generated/agent-fold/index.d.ts +8 -6
  8. package/dist/generated/agent-harness/index.d.ts +1 -1
  9. package/dist/generated/agent-harness/index.js +1 -1
  10. package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
  11. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  12. package/dist/generated/auth/index.js +1 -1
  13. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  14. package/dist/generated/auth/types.gen.d.ts +36 -17
  15. package/dist/generated/cognition/index.d.ts +1 -1
  16. package/dist/generated/cognition/index.js +1 -1
  17. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  18. package/dist/generated/cognition/types.gen.d.ts +473 -4
  19. package/dist/generated/connection/types.gen.d.ts +1 -1
  20. package/dist/generated/notification/index.d.ts +1 -1
  21. package/dist/generated/notification/types.gen.d.ts +36 -1
  22. package/dist/generated/scheduled-action/index.d.ts +1 -1
  23. package/dist/generated/scheduled-action/index.js +1 -1
  24. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  25. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  26. package/dist/generated/storage/index.d.ts +1 -1
  27. package/dist/generated/storage/index.js +1 -1
  28. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  29. package/dist/generated/storage/types.gen.d.ts +3969 -374
  30. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  31. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  32. package/dist/src/entities/activity/entity.d.ts +7 -0
  33. package/dist/src/entities/activity/namespace.d.ts +58 -0
  34. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  35. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  36. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  37. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  38. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  39. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  40. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  41. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  42. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  43. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  44. package/dist/src/entities/agents/agent.d.ts +98 -3
  45. package/dist/src/entities/agents/namespace.d.ts +52 -8
  46. package/dist/src/entities/ai/namespace.d.ts +9 -1
  47. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  48. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  49. package/dist/src/entities/bots/bot.d.ts +38 -6
  50. package/dist/src/entities/bots/namespace.d.ts +13 -1
  51. package/dist/src/entities/bots/token.d.ts +6 -1
  52. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  53. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  54. package/dist/src/entities/calendar/booking.d.ts +15 -0
  55. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  56. package/dist/src/entities/calendar/event.d.ts +59 -9
  57. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  58. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  59. package/dist/src/entities/calls/call-record.d.ts +90 -14
  60. package/dist/src/entities/calls/connection.d.ts +7 -1
  61. package/dist/src/entities/calls/message.d.ts +27 -5
  62. package/dist/src/entities/calls/namespace.d.ts +15 -3
  63. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  64. package/dist/src/entities/channels/access-request.d.ts +10 -2
  65. package/dist/src/entities/channels/activity.d.ts +20 -4
  66. package/dist/src/entities/channels/channel.d.ts +130 -23
  67. package/dist/src/entities/channels/labels.d.ts +41 -7
  68. package/dist/src/entities/channels/message.d.ts +41 -7
  69. package/dist/src/entities/channels/namespace.d.ts +28 -3
  70. package/dist/src/entities/channels/post.test.d.ts +1 -0
  71. package/dist/src/entities/channels/thread.d.ts +19 -3
  72. package/dist/src/entities/chats/chat.d.ts +56 -6
  73. package/dist/src/entities/chats/generation.d.ts +11 -2
  74. package/dist/src/entities/chats/namespace.d.ts +10 -2
  75. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  76. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  77. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  78. package/dist/src/entities/crm/company.d.ts +63 -15
  79. package/dist/src/entities/crm/contact.d.ts +60 -13
  80. package/dist/src/entities/crm/namespace.d.ts +85 -11
  81. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  82. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  83. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  84. package/dist/src/entities/databases/column.d.ts +54 -7
  85. package/dist/src/entities/databases/database.d.ts +126 -12
  86. package/dist/src/entities/databases/namespace.d.ts +16 -4
  87. package/dist/src/entities/databases/row.d.ts +2 -0
  88. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  89. package/dist/src/entities/databases/table.d.ts +64 -10
  90. package/dist/src/entities/databases/view.d.ts +27 -5
  91. package/dist/src/entities/databases/webhook.d.ts +8 -1
  92. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  93. package/dist/src/entities/documents/anchor.d.ts +12 -2
  94. package/dist/src/entities/documents/comment.d.ts +29 -5
  95. package/dist/src/entities/documents/document.d.ts +243 -20
  96. package/dist/src/entities/documents/markdown.d.ts +25 -0
  97. package/dist/src/entities/documents/namespace.d.ts +132 -13
  98. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  99. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  100. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  101. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  102. package/dist/src/entities/documents/version.d.ts +5 -1
  103. package/dist/src/entities/email/attachment.d.ts +3 -0
  104. package/dist/src/entities/email/draft.d.ts +61 -9
  105. package/dist/src/entities/email/filter.d.ts +12 -2
  106. package/dist/src/entities/email/label.d.ts +7 -1
  107. package/dist/src/entities/email/link.d.ts +5 -1
  108. package/dist/src/entities/email/message.d.ts +55 -8
  109. package/dist/src/entities/email/namespace.d.ts +127 -21
  110. package/dist/src/entities/email/thread.d.ts +99 -16
  111. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  112. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  113. package/dist/src/entities/entity.d.ts +56 -6
  114. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  115. package/dist/src/entities/external-chat/message.d.ts +1 -1
  116. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  117. package/dist/src/entities/external-chat/send.d.ts +10 -2
  118. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  120. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  121. package/dist/src/entities/forms/form.d.ts +71 -13
  122. package/dist/src/entities/forms/namespace.d.ts +10 -2
  123. package/dist/src/entities/forms/question.d.ts +35 -7
  124. package/dist/src/entities/forms/response.d.ts +25 -5
  125. package/dist/src/entities/forms/section.d.ts +15 -3
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  128. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  129. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  130. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  131. package/dist/src/entities/images/image.d.ts +16 -5
  132. package/dist/src/entities/images/namespace.d.ts +8 -1
  133. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  134. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  135. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  136. package/dist/src/entities/me/namespace.d.ts +27 -2
  137. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  138. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  139. package/dist/src/entities/memory/namespace.d.ts +49 -0
  140. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  141. package/dist/src/entities/messages/discussion.d.ts +84 -0
  142. package/dist/src/entities/messages/thread.d.ts +19 -5
  143. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  144. package/dist/src/entities/notifications/notification.d.ts +29 -5
  145. package/dist/src/entities/pins/namespace.d.ts +23 -4
  146. package/dist/src/entities/projects/namespace.d.ts +29 -0
  147. package/dist/src/entities/projects/project.d.ts +47 -6
  148. package/dist/src/entities/properties/namespace.d.ts +67 -11
  149. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  150. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  151. package/dist/src/entities/properties/property-option.d.ts +14 -2
  152. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  153. package/dist/src/entities/routines/namespace.d.ts +128 -7
  154. package/dist/src/entities/routines/routine.d.ts +111 -25
  155. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  156. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  157. package/dist/src/entities/search/namespace.d.ts +5 -1
  158. package/dist/src/entities/sharing/access.d.ts +50 -9
  159. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  160. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  161. package/dist/src/entities/tasks/task.d.ts +7 -1
  162. package/dist/src/entities/teams/invite.d.ts +3 -0
  163. package/dist/src/entities/teams/namespace.d.ts +10 -2
  164. package/dist/src/entities/teams/team.d.ts +7 -0
  165. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  166. package/dist/src/entities/users/namespace.d.ts +19 -1
  167. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  168. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  169. package/dist/src/entities/users/user.d.ts +52 -1
  170. package/dist/src/entities/web/namespace.d.ts +6 -0
  171. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  172. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  173. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  174. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  175. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  176. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  177. package/dist/src/entities/workspace/query.d.ts +5 -1
  178. package/dist/src/events/hydrate/user.d.ts +14 -0
  179. package/dist/src/events/receiver.d.ts +2 -0
  180. package/dist/src/events/types.d.ts +2 -1
  181. package/dist/src/macro.d.ts +33 -5
  182. package/dist/src/macro.js +15635 -10132
  183. package/dist/src/utils/lazy.d.ts +7 -1
  184. package/package.json +1 -1
  185. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -21,19 +21,42 @@ export declare class AccountManagerGrant extends MacroEntity<AccountManagerGrant
21
21
  readonly claimedAt: () => Promise<string | undefined>;
22
22
  /** When the token was last used, to the minute. */
23
23
  readonly lastUsedAt: () => Promise<string | undefined>;
24
- /** The account being managed. */
24
+ /**
25
+ * The account being managed.
26
+ *
27
+ * @readonly
28
+ */
25
29
  managed(): Promise<User>;
26
- /** The agent account doing the managing. */
30
+ /**
31
+ * The agent account doing the managing.
32
+ *
33
+ * @readonly
34
+ */
27
35
  manager(): Promise<User>;
28
- /** Approve a request you didn't make. Only the side that didn't ask can. */
36
+ /**
37
+ * Approve a request you didn't make. Only the side that didn't ask can.
38
+ *
39
+ * @destructive
40
+ */
29
41
  approve(): Promise<void>;
30
- /** Decline a request you didn't make. Only the side that didn't ask can. */
42
+ /**
43
+ * Decline a request you didn't make. Only the side that didn't ask can.
44
+ *
45
+ * @destructive
46
+ */
31
47
  decline(): Promise<void>;
32
48
  /**
33
49
  * Get the token for the managed account. Only the manager can, and only once:
34
50
  * save it now. Use it as the SDK's `token` to act as the managed account.
51
+ *
52
+ * @destructive
35
53
  */
36
54
  claimToken(): Promise<string>;
37
- /** End the grant, stopping its token immediately. Either side can. */
55
+ /**
56
+ * End the grant, stopping its token immediately. Either side can.
57
+ *
58
+ * @destructive
59
+ * @idempotent
60
+ */
38
61
  revoke(): Promise<void>;
39
62
  }
@@ -7,11 +7,23 @@ export declare class AccountManagerNamespace {
7
7
  constructor(client: MacroClient);
8
8
  /** Construct a lazy grant handle. */
9
9
  byId(id: string): AccountManagerGrant;
10
- /** List the approved and active managers of the caller's account. */
10
+ /**
11
+ * List the approved and active managers of the caller's account.
12
+ *
13
+ * @readonly
14
+ */
11
15
  list(): Promise<AccountManagerGrant[]>;
12
- /** Ask to manage `user`'s account, in your DM. The caller must be an agent account and `user` a person. */
16
+ /**
17
+ * Ask to manage `user`'s account, in your DM. The caller must be an agent account and `user` a person.
18
+ *
19
+ * @write
20
+ */
13
21
  askToManage(user: User): Promise<AccountManagerGrant>;
14
- /** Ask `user`, an agent account, to manage the caller's account, in your DM. The caller must be a person. */
22
+ /**
23
+ * Ask `user`, an agent account, to manage the caller's account, in your DM. The caller must be a person.
24
+ *
25
+ * @write
26
+ */
15
27
  askToBeManagedBy(user: User): Promise<AccountManagerGrant>;
16
28
  private request;
17
29
  }
@@ -0,0 +1,7 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { EntityReference } from '../reference';
3
+ /**
4
+ * @internal A handle for an activity row's entity, or `undefined` for kinds
5
+ * addressed by more than their own id (channel messages, database rows).
6
+ */
7
+ export declare function activityEntity(client: MacroClient, type: string, id: string): EntityReference | undefined;
@@ -0,0 +1,58 @@
1
+ import type { ToolActivityAction } from '../../../generated/cognition/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { EntityReference } from '../reference';
4
+ import { User } from '../users/user';
5
+ /** What an activity event did; property changes carry readable `propertyName` and option labels. */
6
+ export type ActivityAction = ToolActivityAction;
7
+ /** One action attributed to the acting user. */
8
+ export interface ActivityEvent {
9
+ /** Who mechanically acted: the user, or an agent acting for them. */
10
+ actor: User;
11
+ /** The kind of item acted on, e.g. `document`, `channel`, `email_thread`. */
12
+ entityType: string;
13
+ /** The item acted on; `undefined` for kinds without a standalone handle (channel messages, database rows). */
14
+ entity: EntityReference | undefined;
15
+ /** What was done. */
16
+ action: ActivityAction;
17
+ /** When it happened, RFC 3339. */
18
+ occurredAt: string;
19
+ }
20
+ /** A bounded slice of the acting user's activity. */
21
+ export interface ActivityRange {
22
+ /** Matching events, newest first, at most 100. */
23
+ activities: ActivityEvent[];
24
+ /** More than 100 events matched; narrow the range to see the rest. */
25
+ truncated: boolean;
26
+ }
27
+ /**
28
+ * The acting user's own action history across Macro.
29
+ *
30
+ * @routing Use when reading what the user did, opened, edited or sent in a time range, or a teammate's or project's history; not everything that changed in the workspace (`macro.workspace`).
31
+ *
32
+ * @agent `macro.activity.mine` lists the user's own raw actions (opened,
33
+ * edited, sent), including actions agents took for them; `User.activity`
34
+ * reads privacy-reviewed daily, weekly and monthly summaries of the user's
35
+ * or a teammate's work; `Initiative.activity` reads one project's history.
36
+ * Answer with item names and readable property labels, never ids:
37
+ * read names through the returned handles. A range returns at most 100
38
+ * events; when `truncated` is true, split the range and read each part.
39
+ */
40
+ export declare class ActivityNamespace {
41
+ private readonly client;
42
+ constructor(client: MacroClient);
43
+ /**
44
+ * The acting user's actions in `[from, to)`, newest first, at most 100; when
45
+ * `truncated` is true, split the range and read each part.
46
+ *
47
+ * @example
48
+ * const to = new Date();
49
+ * const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000);
50
+ * const { activities, truncated } = await macro.activity.mine({ from, to });
51
+ *
52
+ * @readonly
53
+ */
54
+ mine(range: {
55
+ from: Date | string;
56
+ to: Date | string;
57
+ }): Promise<ActivityRange>;
58
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -16,9 +16,17 @@ export declare class AgentInvocation {
16
16
  private constructor();
17
17
  /** Construct a handle without making a request. */
18
18
  static byId(client: MacroClient, session: AgentSession, id: string): AgentInvocation;
19
- /** The session that owns this invocation. */
19
+ /**
20
+ * The session that owns this invocation.
21
+ *
22
+ * @readonly
23
+ */
20
24
  session(): AgentSession;
21
- /** Recorded activity caused by this invocation, lazily paginated. */
25
+ /**
26
+ * Recorded activity caused by this invocation, lazily paginated.
27
+ *
28
+ * @readonly
29
+ */
22
30
  activity(options?: Omit<AgentActivityOptions, 'invocation'>): AsyncGenerator<AgentActivity, any, any>;
23
31
  /** Safe identity without an authenticated client. */
24
32
  toJSON(): {
@@ -1,10 +1,11 @@
1
1
  import type { FoldedMessage } from '../../../generated/agent-fold';
2
- import type { AgentAction, AgentMode, AgentSessionChangesResponse, AgentSessionLogResponse, AgentSessionResponse, ArchiveCause, AutoArchivePreferencesBody, CodingPreferencesBody, ControlResponse, PromptAttachment, PullRequestLinkSource, SandboxSize, SessionBot } from '../../../generated/agent-harness/types.gen';
2
+ import type { AgentAction, AgentMode, AgentSessionChangesResponse, AgentSessionLogResponse, AgentSessionResponse, AgentUpdateKind, ArchiveCause, AutoArchivePreferencesBody, CodingPreferencesBody, ControlResponse, PromptAttachment, PullRequestLinkSource, SandboxSize, SessionBot } from '../../../generated/agent-harness/types.gen';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import type { Agent } from '../agents/agent';
5
5
  import { MacroEntity } from '../entity';
6
6
  import { EntityAccess } from '../sharing/access';
7
7
  import { type SharePermissionOptions } from '../sharing/permissions';
8
+ import { Task } from '../tasks/task';
8
9
  import { User } from '../users/user';
9
10
  import { type AgentActivityOptions, AgentInvocation } from './activity';
10
11
  import { CodeExecution } from './code-execution';
@@ -68,6 +69,60 @@ export type SessionPullRequest = {
68
69
  /** When it was linked. */
69
70
  createdAt: string;
70
71
  };
72
+ /** A request a session is waiting on its owner to answer, or a session gone quiet. */
73
+ export type AgentSessionUpdate = {
74
+ /** The session. */
75
+ session: AgentSession;
76
+ /** The session's name. */
77
+ sessionName: string;
78
+ /** The runtime the session runs on. */
79
+ harness: string;
80
+ /** The session's pull request, if it has one. */
81
+ pullRequestUrl?: string;
82
+ /**
83
+ * What the session waits for: `permission` to run a tool, an `elicitation`
84
+ * question, a held `tool_approval`, or `stalled` with no activity for over
85
+ * 20 minutes.
86
+ */
87
+ kind: AgentUpdateKind;
88
+ /** What is asked, or why the session looks stalled. */
89
+ summary: string;
90
+ /** When the request was made, or the session's last activity. */
91
+ since: string;
92
+ /** The choices a permission request offers; empty for other kinds. */
93
+ options: string[];
94
+ };
95
+ /** The caller's sessions waiting for them, newest activity first. */
96
+ export type AgentSessionUpdates = {
97
+ /** One entry per pending request or stalled session. */
98
+ items: AgentSessionUpdate[];
99
+ /** Whether sessions beyond the 25 most recent were left out. */
100
+ truncated: boolean;
101
+ /** Says what was left out, when truncated. */
102
+ truncationNotice?: string;
103
+ };
104
+ /** A tool call the session's runtime holds until its owner answers. */
105
+ export type PendingToolApproval = {
106
+ /** Answer it with {@link ToolApproval.answer}. */
107
+ approval: ToolApproval;
108
+ /** What a person calls the server the tool is on. */
109
+ serverName: string;
110
+ /** The tool called. */
111
+ toolName: string;
112
+ /** What it was called with. */
113
+ arguments: unknown;
114
+ /** Who prompted the turn; absent for a bot on nobody's behalf. */
115
+ requestedBy?: User;
116
+ };
117
+ /** The task a session is linked to. */
118
+ export type LinkedTask = {
119
+ /** The task. */
120
+ task: Task;
121
+ /** Put this in the pull request description so GitHub activity reaches the task. */
122
+ reference: string;
123
+ /** The session's pull request, now linked to the task, if it has one. */
124
+ pullRequestUrl?: string;
125
+ };
71
126
  /** A GitHub repository the caller can point a managed session at. */
72
127
  export type SelectableRepository = {
73
128
  /** The canonical `https://github.com/owner/name` URL, as `createManaged` takes it. */
@@ -81,8 +136,8 @@ export type SelectableRepository = {
81
136
  /** What a managed session is created with. */
82
137
  export type CreateManagedSessionOptions = {
83
138
  /**
84
- * Persona the session runs as, from {@link AgentNamespace.list} or
85
- * {@link Agent.byId}. The caller must be able to use it. Omitted, the
139
+ * Persona the session runs as, from {@link AgentNamespace.coding} or
140
+ * {@link AgentNamespace.list}. The caller must be able to use it. Omitted, the
86
141
  * deployment's default coding persona, or Cursor when `repoUrl` is set.
87
142
  * Its harness, instructions and model apply unless `instructions` or
88
143
  * `model` override them.
@@ -117,13 +172,30 @@ export type CreateManagedSessionOptions = {
117
172
  export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
118
173
  /** Access requests and direct user grants. */
119
174
  readonly access: EntityAccess;
120
- /** Construct an approval handle scoped to this session. */
175
+ /**
176
+ * Construct an approval handle scoped to this session.
177
+ *
178
+ * @readonly
179
+ */
121
180
  toolApprovalById(id: string): ToolApproval;
122
- /** Sharing configuration. */
181
+ /**
182
+ * Sharing configuration.
183
+ *
184
+ * @readonly
185
+ */
123
186
  sharePermissions(): Promise<import("../../../generated/agent-harness").SharePermissionV2>;
124
- /** Replace sharing grants. */
187
+ /**
188
+ * Replace sharing grants.
189
+ *
190
+ * @write
191
+ * @idempotent
192
+ */
125
193
  updateSharePermissions(options: SharePermissionOptions): Promise<import("../../../generated/agent-harness").SharePermissionV2>;
126
- /** The session's URL in the Macro web app; hand it to users as the link. */
194
+ /**
195
+ * The session's URL in the Macro web app; hand it to users as the link.
196
+ *
197
+ * @readonly
198
+ */
127
199
  webUrl(): string;
128
200
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
129
201
  toJSON(): {
@@ -169,6 +241,8 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
169
241
  /**
170
242
  * What opened the session: who or what started it, and what it is about.
171
243
  * Readable by anyone who can view the session, including other agents.
244
+ *
245
+ * @readonly
172
246
  */
173
247
  origin(): Promise<SessionOrigin>;
174
248
  /**
@@ -205,29 +279,72 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
205
279
  * can view, oldest link first.
206
280
  */
207
281
  static forPullRequest(client: MacroClient, url: string): Promise<AgentSession[]>;
282
+ /**
283
+ * The caller's coding sessions waiting for an answer from them, or stalled
284
+ * for over 20 minutes, newest activity first. Only the 25 most recent such
285
+ * sessions are inspected.
286
+ */
287
+ static updates(client: MacroClient): Promise<AgentSessionUpdates>;
288
+ /**
289
+ * Tool calls this session's runtime holds until its owner approves them,
290
+ * oldest first. Answer each with {@link ToolApproval.answer}; only the
291
+ * owner may approve or decline. Permission requests and questions from the
292
+ * agent itself are answered with {@link control}.
293
+ *
294
+ * @readonly
295
+ */
296
+ pendingApprovals(): Promise<PendingToolApproval[]>;
297
+ /**
298
+ * Link this session to the task it works on, replacing any earlier link.
299
+ * Only the session's owner can link it, to a task they can view. The
300
+ * session's pull request, now or later, is linked to the task too.
301
+ *
302
+ * @write
303
+ */
304
+ linkTask(task: Task): Promise<LinkedTask>;
208
305
  /**
209
306
  * The GitHub pull requests linked to this session: the one its agent
210
307
  * opened and any a person linked, oldest first.
308
+ *
309
+ * @readonly
211
310
  */
212
311
  pullRequests(): Promise<SessionPullRequest[]>;
213
312
  /**
214
313
  * Link the GitHub pull request at `url` to this session. Linking one that
215
314
  * is already linked changes nothing.
315
+ *
316
+ * @write
317
+ * @idempotent
216
318
  */
217
319
  linkPullRequest(url: string): Promise<void>;
218
320
  /**
219
321
  * Unlink a GitHub pull request a person linked to this session. The pull
220
322
  * request the session's agent opened stays linked.
323
+ *
324
+ * @write
325
+ * @idempotent
221
326
  */
222
327
  unlinkPullRequest(url: string): Promise<void>;
223
- /** This session's auto-archive settings, and when a trigger archived it. */
328
+ /**
329
+ * This session's auto-archive settings, and when a trigger archived it.
330
+ *
331
+ * @readonly
332
+ */
224
333
  autoArchive(): Promise<SessionAutoArchive>;
225
334
  /**
226
335
  * Replace this session's auto-archive choices. Owner only; a trigger left
227
336
  * `undefined` follows the owner's default.
337
+ *
338
+ * @write
339
+ * @idempotent
228
340
  */
229
341
  setAutoArchive(overrides: AutoArchiveOverrides): Promise<void>;
230
- /** Rename this session. */
342
+ /**
343
+ * Rename this session.
344
+ *
345
+ * @write
346
+ * @idempotent
347
+ */
231
348
  rename(name: string): Promise<void>;
232
349
  /**
233
350
  * Register this session as the caller's work, so it shows as what the caller
@@ -239,22 +356,43 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
239
356
  * The registration ends on its own when the session's pull requests finish,
240
357
  * when it is archived, after a day without work, or after a week blocked on
241
358
  * input. A later turn does not register it again.
359
+ *
360
+ * @write
361
+ * @idempotent
242
362
  */
243
363
  registerAsWork(): Promise<RegisteredWork>;
244
364
  /**
245
365
  * End the caller's registration of this session as its work. Doing it again
246
366
  * changes nothing. The session itself is untouched.
367
+ *
368
+ * @write
369
+ * @idempotent
247
370
  */
248
371
  unregisterAsWork(): Promise<void>;
249
372
  /** The caller's active registrations, newest first. */
250
373
  static listRegisteredWork(client: MacroClient): Promise<RegisteredWork[]>;
251
374
  private static registeredWork;
252
- /** Archive this session, making it read-only until unarchived. */
375
+ /**
376
+ * Archive this session, making it read-only until unarchived.
377
+ *
378
+ * @write
379
+ * @idempotent
380
+ */
253
381
  archive(): Promise<void>;
254
- /** Restore an archived session so it can be edited and prompted again. */
382
+ /**
383
+ * Restore an archived session so it can be edited and prompted again.
384
+ *
385
+ * @write
386
+ * @idempotent
387
+ */
255
388
  unarchive(): Promise<void>;
256
389
  private setArchived;
257
- /** Resize this session's sandbox and remember the size as the owner's default. */
390
+ /**
391
+ * Resize this session's sandbox and remember the size as the owner's default.
392
+ *
393
+ * @write
394
+ * @idempotent
395
+ */
258
396
  setSandboxSize(size: SandboxSize): Promise<SandboxSize>;
259
397
  /** The caller's default sandbox size for new `@coder` sessions. */
260
398
  static defaultSandboxSize(client: MacroClient): Promise<SandboxSize>;
@@ -275,6 +413,9 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
275
413
  * action derives once it dispatches. A `queued` status means a turn was
276
414
  * running: the action waits in the session's queue ({@link queue}) and
277
415
  * dispatches when that turn ends.
416
+ *
417
+ * @destructive
418
+ * @openworld
278
419
  */
279
420
  control(action: AgentAction): Promise<ControlResponse>;
280
421
  /**
@@ -283,18 +424,37 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
283
424
  * `attachments` are files the prompt refers to, each by a URL the agent
284
425
  * can fetch (a static file service URL in practice); they reach the agent
285
426
  * as ACP `resource_link` blocks after the text.
427
+ *
428
+ * @destructive
429
+ * @openworld
286
430
  */
287
431
  prompt(text: string, attachments?: PromptAttachment[]): Promise<ControlResponse>;
288
432
  /**
289
433
  * The actions waiting to dispatch in this session, oldest first. Each can
290
434
  * be edited or removed until it dispatches.
435
+ *
436
+ * @readonly
291
437
  */
292
438
  queue(): Promise<QueuedAction[]>;
293
- /** Read the latest captured GitHub pull request changes and capture status. */
439
+ /**
440
+ * Read the latest captured GitHub pull request changes and capture status.
441
+ *
442
+ * @readonly
443
+ */
294
444
  changes(): Promise<AgentSessionChangesResponse>;
295
- /** Read the unified diff of the latest captured changeset. */
445
+ /**
446
+ * Read the unified diff of the latest captured changeset.
447
+ *
448
+ * @readonly
449
+ */
296
450
  changesPatch(): Promise<string>;
297
- /** Request a fresh capture and return the current state while it runs. */
451
+ /**
452
+ * Request a fresh capture and return the current state while it runs.
453
+ *
454
+ * @write
455
+ * @idempotent
456
+ * @openworld
457
+ */
298
458
  refreshChanges(): Promise<AgentSessionChangesResponse>;
299
459
  /**
300
460
  * Read this session's whole history as the conversation the app renders:
@@ -303,9 +463,15 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
303
463
  * session the caller can view, live or finished, so it is the way to read
304
464
  * what another agent session did. Prefer it to {@link log}, which returns
305
465
  * raw protocol frames.
466
+ *
467
+ * @readonly
306
468
  */
307
469
  foldedLog(): Promise<FoldedAgentSessionLog>;
308
- /** Read the complete raw protocol log for this session. */
470
+ /**
471
+ * Read the complete raw protocol log for this session.
472
+ *
473
+ * @readonly
474
+ */
309
475
  log(): Promise<AgentSessionLogResponse>;
310
476
  /** Persisted reviews scoped to this session, with or without a code execution. */
311
477
  readonly reviews: {
@@ -320,12 +486,21 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
320
486
  readonly codeExecutions: {
321
487
  byId: (id: string) => CodeExecution;
322
488
  };
323
- /** Recorded activity caused by this session, lazily paginated newest first. */
489
+ /**
490
+ * Recorded activity caused by this session, lazily paginated newest first.
491
+ *
492
+ * @readonly
493
+ */
324
494
  activity(options?: AgentActivityOptions): AsyncGenerator<import("./activity").AgentActivity, any, any>;
325
495
  /** Code-mode invocation handles, distinct from saved code executions. */
326
496
  readonly invocations: {
327
497
  byId: (id: string) => AgentInvocation;
328
498
  };
329
- /** Delete this session and any live resources it owns. */
499
+ /**
500
+ * Delete this session and any live resources it owns.
501
+ *
502
+ * @destructive
503
+ * @idempotent
504
+ */
330
505
  delete(): Promise<void>;
331
506
  }
@@ -20,7 +20,11 @@ export declare class CodeExecution extends MacroEntity<ExecutionRecord> {
20
20
  readonly views: {
21
21
  present: (view: SessionView) => Promise<void>;
22
22
  };
23
- /** The session this execution belongs to. */
23
+ /**
24
+ * The session this execution belongs to.
25
+ *
26
+ * @readonly
27
+ */
24
28
  session(): AgentSession;
25
29
  /** Saved execution state. Call refresh to observe subsequent changes. */
26
30
  readonly status: () => Promise<import("../../../generated/agent-harness").ExecutionStatus>;
@@ -30,9 +34,17 @@ export declare class CodeExecution extends MacroEntity<ExecutionRecord> {
30
34
  readonly calls: () => Promise<import("../../../generated/agent-harness").RecordedToolCall[]>;
31
35
  /** Execution failure text, when present. */
32
36
  readonly error: () => Promise<string | undefined>;
33
- /** The program's returned JSON; preserves an explicit null result. */
37
+ /**
38
+ * The program's returned JSON; preserves an explicit null result.
39
+ *
40
+ * @readonly
41
+ */
34
42
  result(): Promise<unknown>;
35
- /** Reload the saved state, for example after a running execution completes. */
43
+ /**
44
+ * Reload the saved state, for example after a running execution completes.
45
+ *
46
+ * @readonly
47
+ */
36
48
  refresh(): Promise<this>;
37
49
  }
38
50
  /** JSON data returned to the model, plus references to independently saved UI. */
@@ -4,7 +4,11 @@ import { Agent } from '../agents/agent';
4
4
  import type { Channel } from '../channels/channel';
5
5
  import { Message } from '../channels/message';
6
6
  import { AgentSession } from './agent-session';
7
- /** An agent's conversation in one channel. */
7
+ /**
8
+ * An agent's conversation in one channel.
9
+ *
10
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
11
+ */
8
12
  export declare class AgentConversation {
9
13
  private readonly client;
10
14
  /** Parent channel. */
@@ -13,17 +17,33 @@ export declare class AgentConversation {
13
17
  constructor(client: MacroClient,
14
18
  /** Parent channel. */
15
19
  channel: Channel, record: AgentConversationDto);
16
- /** The agent taking part. */
20
+ /**
21
+ * The agent taking part.
22
+ *
23
+ * @readonly
24
+ */
17
25
  agent(): Agent;
18
- /** Conversation sessions with their current flag. */
26
+ /**
27
+ * Conversation sessions with their current flag.
28
+ *
29
+ * @readonly
30
+ */
19
31
  sessions(): {
20
32
  session: AgentSession;
21
33
  isCurrent: boolean;
22
34
  createdAt: string;
23
35
  }[];
24
- /** Recorded conversation turns. */
36
+ /**
37
+ * Recorded conversation turns.
38
+ *
39
+ * @readonly
40
+ */
25
41
  turns(): ConversationTurn[];
26
- /** Start a fresh conversation from one of its sessions. */
42
+ /**
43
+ * Start a fresh conversation from one of its sessions.
44
+ *
45
+ * @write
46
+ */
27
47
  startFresh(session: AgentSession): Promise<void>;
28
48
  /** Serialize scoped identity. */
29
49
  toJSON(): {
@@ -31,7 +51,11 @@ export declare class AgentConversation {
31
51
  agentId: string;
32
52
  };
33
53
  }
34
- /** One agent conversation turn, identified by its source message. */
54
+ /**
55
+ * One agent conversation turn, identified by its source message.
56
+ *
57
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
58
+ */
35
59
  export declare class ConversationTurn {
36
60
  private readonly client;
37
61
  /** Parent conversation. */
@@ -40,11 +64,24 @@ export declare class ConversationTurn {
40
64
  constructor(client: MacroClient,
41
65
  /** Parent conversation. */
42
66
  conversation: AgentConversation, record: AgentConversationTurnDto);
43
- /** Originating message. */
67
+ /**
68
+ * Originating message.
69
+ *
70
+ * @readonly
71
+ */
44
72
  source(): Message;
45
- /** Session that handled this turn. */
73
+ /**
74
+ * Session that handled this turn.
75
+ *
76
+ * @readonly
77
+ */
46
78
  session(): AgentSession;
47
- /** Retry with a caller persisted action nonce. Never retries automatically. */
79
+ /**
80
+ * Retry with a caller persisted action nonce. Never retries automatically.
81
+ *
82
+ * @write
83
+ * @idempotent
84
+ */
48
85
  retry(actionId: string): Promise<void>;
49
86
  /** Serialize scoped identity. */
50
87
  toJSON(): {