@macro-inc/sdk 0.5.0 → 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 (138) hide show
  1. package/README.md +156 -23
  2. package/dist/{chunk-3SW6QVDV.js → chunk-4MI52GWV.js} +60 -1
  3. package/dist/{chunk-GT5EUYOR.js → chunk-HO75UE4Z.js} +133 -0
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-HIW6KU2I.js → chunk-SJ6S2GAT.js} +712 -14
  6. package/dist/{chunk-J2VK3NOR.js → chunk-SK5CMXRV.js} +44 -14
  7. package/dist/{chunk-UVJLWLSJ.js → chunk-TMTYN2UK.js} +190 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +194 -8
  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 +33 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +341 -8
  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 +69 -1
  18. package/dist/generated/auth/types.gen.d.ts +734 -3
  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 +23 -6
  23. package/dist/generated/cognition/types.gen.d.ts +202 -114
  24. package/dist/generated/contacts/index.d.ts +1 -1
  25. package/dist/generated/contacts/index.js +1 -1
  26. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  27. package/dist/generated/contacts/types.gen.d.ts +56 -0
  28. package/dist/generated/email/types.gen.d.ts +8 -2
  29. package/dist/generated/notification/index.d.ts +1 -1
  30. package/dist/generated/notification/index.js +1 -1
  31. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  32. package/dist/generated/notification/types.gen.d.ts +138 -0
  33. package/dist/generated/scheduled-action/index.d.ts +1 -1
  34. package/dist/generated/scheduled-action/index.js +1 -1
  35. package/dist/generated/scheduled-action/sdk.gen.d.ts +92 -2
  36. package/dist/generated/scheduled-action/types.gen.d.ts +1455 -21
  37. package/dist/generated/search/index.d.ts +1 -1
  38. package/dist/generated/search/types.gen.d.ts +50 -11
  39. package/dist/generated/storage/index.d.ts +1 -1
  40. package/dist/generated/storage/index.js +1 -1
  41. package/dist/generated/storage/sdk.gen.d.ts +309 -15
  42. package/dist/generated/storage/types.gen.d.ts +12437 -8899
  43. package/dist/src/entities/agent-sessions/activity.d.ts +3 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +17 -5
  45. package/dist/src/entities/agent-sessions/namespace.d.ts +5 -4
  46. package/dist/src/entities/agent-sessions/review.d.ts +1 -1
  47. package/dist/src/entities/ai/namespace.d.ts +2 -2
  48. package/dist/src/entities/api-keys/namespace.d.ts +5 -2
  49. package/dist/src/entities/bots/bot.d.ts +6 -3
  50. package/dist/src/entities/calendar/booking-namespace.d.ts +1 -1
  51. package/dist/src/entities/calendar/calendar.d.ts +3 -2
  52. package/dist/src/entities/calendar/event.d.ts +9 -0
  53. package/dist/src/entities/calendar/namespace.d.ts +3 -2
  54. package/dist/src/entities/calls/call-record.d.ts +19 -5
  55. package/dist/src/entities/canvases/canvas.d.ts +5 -0
  56. package/dist/src/entities/channels/channel.d.ts +27 -7
  57. package/dist/src/entities/channels/message.d.ts +65 -2
  58. package/dist/src/entities/channels/message.test.d.ts +1 -0
  59. package/dist/src/entities/channels/namespace.d.ts +9 -4
  60. package/dist/src/entities/channels/post.d.ts +13 -7
  61. package/dist/src/entities/channels/share.d.ts +9 -0
  62. package/dist/src/entities/channels/share.test.d.ts +1 -0
  63. package/dist/src/entities/channels/thread.d.ts +5 -1
  64. package/dist/src/entities/chats/chat.d.ts +1 -1
  65. package/dist/src/entities/chats/namespace.d.ts +1 -1
  66. package/dist/src/entities/connected-apps/connected-app.d.ts +2 -1
  67. package/dist/src/entities/connected-apps/namespace.d.ts +2 -0
  68. package/dist/src/entities/crm/company.d.ts +1 -1
  69. package/dist/src/entities/crm/contact.d.ts +44 -3
  70. package/dist/src/entities/crm/namespace.d.ts +30 -13
  71. package/dist/src/entities/crm/pipeline-entry.d.ts +10 -3
  72. package/dist/src/entities/crm/pipeline.d.ts +39 -20
  73. package/dist/src/entities/crm/pipelines.d.ts +33 -5
  74. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  75. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  76. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  77. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  78. package/dist/src/entities/databases/database.d.ts +34 -6
  79. package/dist/src/entities/databases/namespace.d.ts +26 -6
  80. package/dist/src/entities/databases/saved-query.d.ts +7 -1
  81. package/dist/src/entities/databases/table.d.ts +9 -0
  82. package/dist/src/entities/databases/view.d.ts +10 -0
  83. package/dist/src/entities/documents/create.test.d.ts +1 -0
  84. package/dist/src/entities/documents/document.d.ts +41 -6
  85. package/dist/src/entities/documents/namespace.d.ts +17 -3
  86. package/dist/src/entities/email/draft.d.ts +2 -2
  87. package/dist/src/entities/email/message.d.ts +18 -7
  88. package/dist/src/entities/email/namespace.d.ts +11 -7
  89. package/dist/src/entities/email/thread.d.ts +26 -3
  90. package/dist/src/entities/entity.d.ts +10 -1
  91. package/dist/src/entities/external-chat/chat.d.ts +19 -2
  92. package/dist/src/entities/foreign/namespace.d.ts +1 -1
  93. package/dist/src/entities/forms/form.d.ts +20 -1
  94. package/dist/src/entities/harnesses/namespace.d.ts +1 -1
  95. package/dist/src/entities/harnesses/pairing.d.ts +2 -1
  96. package/dist/src/entities/imports/entry.d.ts +65 -0
  97. package/dist/src/entities/imports/namespace.d.ts +103 -0
  98. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  99. package/dist/src/entities/initiatives/initiative.d.ts +14 -4
  100. package/dist/src/entities/initiatives/namespace.d.ts +4 -2
  101. package/dist/src/entities/me/namespace.d.ts +1 -1
  102. package/dist/src/entities/meetings/meeting.d.ts +2 -1
  103. package/dist/src/entities/notifications/namespace.d.ts +2 -1
  104. package/dist/src/entities/notifications/notification.d.ts +2 -1
  105. package/dist/src/entities/passwords/item.d.ts +118 -0
  106. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  107. package/dist/src/entities/projects/namespace.d.ts +1 -1
  108. package/dist/src/entities/projects/project.d.ts +11 -1
  109. package/dist/src/entities/referrals/namespace.d.ts +1 -1
  110. package/dist/src/entities/routines/namespace.d.ts +81 -18
  111. package/dist/src/entities/routines/routine.d.ts +65 -4
  112. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  113. package/dist/src/entities/saved-views/namespace.d.ts +2 -1
  114. package/dist/src/entities/search/exclusions.d.ts +6 -0
  115. package/dist/src/entities/search/namespace.d.ts +4 -2
  116. package/dist/src/entities/search/options.d.ts +3 -2
  117. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  118. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  119. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  120. package/dist/src/entities/tasks/namespace.d.ts +6 -5
  121. package/dist/src/entities/tasks/task.d.ts +14 -2
  122. package/dist/src/entities/teams/team.d.ts +16 -3
  123. package/dist/src/entities/ui/app-link.d.ts +24 -0
  124. package/dist/src/entities/ui/namespace.d.ts +75 -0
  125. package/dist/src/entities/users/namespace.d.ts +7 -3
  126. package/dist/src/entities/web/namespace.d.ts +2 -2
  127. package/dist/src/entities/workspace/namespace.d.ts +5 -3
  128. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  129. package/dist/src/events/hydrate/document.d.ts +5 -0
  130. package/dist/src/macro.d.ts +26 -1
  131. package/dist/src/macro.js +4086 -1234
  132. package/dist/src/utils/activity.d.ts +2 -0
  133. package/dist/src/utils/index.d.ts +1 -1
  134. package/dist/src/utils/lazy.d.ts +13 -0
  135. package/dist/src/utils/options.d.ts +7 -0
  136. package/dist/src/utils/pagination.d.ts +16 -0
  137. package/dist/src/utils/verbs.d.ts +3 -0
  138. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- import type { CreateInitiativeRequest, InitiativeDetail } from '../../../generated/storage/types.gen';
1
+ import type { CreateInitiativeRequest, EntityAppearance, InitiativeDetail } from '../../../generated/storage/types.gen';
2
2
  import type { RichMessage } from '../../mentions';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import { MacroEntity } from '../entity';
@@ -61,6 +61,15 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
61
61
  protected fetch(): Promise<InitiativeDetail>;
62
62
  /** Display name. */
63
63
  readonly name: () => Promise<string>;
64
+ /** Shared icon and color overrides. */
65
+ readonly appearance: () => Promise<EntityAppearance | undefined>;
66
+ /**
67
+ * Replace shared appearance. Pass {} to reset both overrides.
68
+ *
69
+ * @write
70
+ * @idempotent
71
+ */
72
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
64
73
  /** Owner. */
65
74
  readonly owner: () => Promise<User>;
66
75
  /** Assigned members. */
@@ -75,8 +84,8 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
75
84
  /** Sharing configuration. */
76
85
  readonly sharePermissions: () => Promise<import("../../../generated/storage").SharePermissionV2>;
77
86
  /**
78
- * The description as GitHub-flavored Markdown; empty while no one has opened
79
- * or written it.
87
+ * The description as Macro's lossless Markdown, with chips, tables and other
88
+ * rich content as `<m-*>` tags; empty while no one has opened or written it.
80
89
  *
81
90
  * @readonly
82
91
  */
@@ -147,7 +156,7 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
147
156
  sharePermission?: SharePermissionOptions;
148
157
  }): Promise<void>;
149
158
  /**
150
- * This initiative's history, newest first, auto-paginated: creation, edits,
159
+ * This initiative's history, newest first, auto-paginated (`maxItems` caps the total): creation, edits,
151
160
  * property changes and tasks added or removed, optionally within
152
161
  * `[after, before)`.
153
162
  *
@@ -164,6 +173,7 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
164
173
  activity(window?: {
165
174
  after?: Date | string;
166
175
  before?: Date | string;
176
+ maxItems?: number;
167
177
  }): AsyncGenerator<InitiativeActivityEntry>;
168
178
  /**
169
179
  * Delete this initiative.
@@ -1,4 +1,5 @@
1
1
  import type { InitiativePageRow } from '../../../generated/storage/types.gen';
2
+ import { type IterationOptions } from '../../utils';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { User } from '../users/user';
4
5
  import { Initiative, type InitiativeOptions } from './initiative';
@@ -13,7 +14,7 @@ export type InitiativeStatus = 'not_started' | 'in_progress' | 'in_review' | 'co
13
14
  /** An initiative's canonical Priority. */
14
15
  export type InitiativePriority = 'low' | 'medium' | 'high' | 'urgent';
15
16
  /** Filters and order for {@link InitiativeNamespace.list}. */
16
- export interface InitiativeListOptions {
17
+ export interface InitiativeListOptions extends IterationOptions {
17
18
  /** Case-insensitive substring of the name. */
18
19
  query?: string;
19
20
  /** Only initiatives with this Status. */
@@ -68,11 +69,12 @@ export declare class InitiativeNamespace {
68
69
  * Initiatives the caller can view that match every given filter, with their
69
70
  * name, Status, Priority, assignees, due date and progress over the tasks the
70
71
  * caller can view; most recently updated first unless `sort` says otherwise.
71
- * Iterate with `for await`; pages load as the loop advances.
72
+ * Iterate with `for await`; pages load as the loop advances, and `maxItems` caps the total.
72
73
  *
73
74
  * @readonly
74
75
  */
75
76
  list(options?: InitiativeListOptions): AsyncGenerator<InitiativeListing>;
77
+ private listPages;
76
78
  /**
77
79
  * Every accessible initiative with its name, in one request.
78
80
  *
@@ -23,7 +23,7 @@ export interface UpdateMeOptions {
23
23
  /**
24
24
  * The authenticated user's own profile.
25
25
  *
26
- * @routing Use when changing the user's own name or profile picture; not looking up other people (`macro.users`).
26
+ * @routing Use when reading who the user is or changing their own name or profile picture; not looking up other people (`macro.users`).
27
27
  */
28
28
  export declare class MeNamespace {
29
29
  private readonly client;
@@ -8,7 +8,8 @@ import type { User } from '../users/user';
8
8
  /** A meeting's schedule and invitation link. */
9
9
  export declare class Meeting extends MacroEntity<MeetingRecord> {
10
10
  /**
11
- * Join this meeting as the current account; always send a program join body.
11
+ * Join this meeting as the current account, always sending a program join
12
+ * body; refused to an agent's program (ExecuteCode, a routine).
12
13
  *
13
14
  * @write
14
15
  * @mcp-exclude Returns a live call connection; MCP calls carry JSON only.
@@ -13,12 +13,13 @@ export declare class NotificationNamespace {
13
13
  /** A handle to a notification by id. */
14
14
  byId(id: string): Notification;
15
15
  /**
16
- * The viewer's notification feed, most recent first, auto-paginated.
16
+ * The viewer's notification feed, most recent first, auto-paginated; `maxItems` caps the total.
17
17
  *
18
18
  * @readonly
19
19
  */
20
20
  list(opts?: {
21
21
  pageSize?: number;
22
+ maxItems?: number;
22
23
  }): AsyncGenerator<Notification>;
23
24
  /**
24
25
  * Mark a batch of notifications as seen.
@@ -12,10 +12,11 @@ export declare class Notification extends MacroEntity<NotificationDetail> {
12
12
  static byId(client: MacroClient, id: string): Notification;
13
13
  /** Build a notification from a list-endpoint record (pre-seeded, no fetch). */
14
14
  static from(client: MacroClient, data: NotificationDetail): Notification;
15
- /** The viewer's notification feed, most recent first, auto-paginated. */
15
+ /** The viewer's notification feed, most recent first, auto-paginated; `maxItems` caps the total. */
16
16
  static list(client: MacroClient, opts?: {
17
17
  pageSize?: number;
18
18
  states?: NotificationState[];
19
+ maxItems?: number;
19
20
  }): AsyncGenerator<Notification>;
20
21
  /** The notification event type (e.g. `channel_mention`). */
21
22
  readonly type: () => Promise<string>;
@@ -0,0 +1,118 @@
1
+ import type { PasswordAgentAccessRequestState, PasswordAgentItemAccess, PasswordAgentSearchHit, PasswordAgentSecretPatch, PasswordAgentSecretSelector, PasswordItemKind, PasswordPermission } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { Team } from '../teams/team';
4
+ /**
5
+ * The one agent wake (a single agent query) a vault call is attributed to:
6
+ * a UUIDv7 the agent's runtime mints per wake. It is untrusted correlation for
7
+ * audit, never authorization, and is never kept across wakes.
8
+ */
9
+ export interface AgentWake {
10
+ /** The wake's UUIDv7. */
11
+ wake: string;
12
+ }
13
+ /** One field of a login or API credential an agent may copy. */
14
+ export type SecretSelector = PasswordAgentSecretSelector;
15
+ /** One disclosed field, for the agent's clipboard; never for model context. */
16
+ export interface DisclosedSecret {
17
+ /** The field's value. */
18
+ value: string;
19
+ /** The committed version it was read from. */
20
+ version: number;
21
+ /** The field that was disclosed. */
22
+ selector: SecretSelector;
23
+ }
24
+ /** A verification code with its conservative remaining lifetime. */
25
+ export interface VerificationCode {
26
+ /** The current code. */
27
+ code: string;
28
+ /** Conservative usable-until time on the server clock. */
29
+ expiresAt: string;
30
+ /** Code period in seconds. */
31
+ periodSeconds: number;
32
+ /**
33
+ * Milliseconds the server measured until `expiresAt`. Subtract the whole
34
+ * time since the request was sent, rounded up, before using the code.
35
+ */
36
+ validForMs: number;
37
+ }
38
+ /** An agent's access request on one item. */
39
+ export interface AgentAccessRequest {
40
+ /** Request lifecycle; `none` when the agent has never requested. */
41
+ status: PasswordAgentAccessRequestState['status'];
42
+ /** Requested permission, when a request exists. */
43
+ permission?: PasswordPermission;
44
+ /** Request revision; 0 when none exists. */
45
+ revision: number;
46
+ /** The agent's current access to the item. */
47
+ access: PasswordAgentItemAccess;
48
+ /** Last transition time, when a request exists. */
49
+ updatedAt?: string;
50
+ }
51
+ /** The wire headers of every agent vault call; mutations also carry the CSRF header. */
52
+ export declare function vaultHeaders(wake: AgentWake): {
53
+ 'X-Macro-Agent-Session-Id': string;
54
+ 'X-Macro-Passwords': string;
55
+ };
56
+ /**
57
+ * A team vault item as seen by the authenticated agent, for one wake. Search
58
+ * hits carry metadata only; values are disclosed one field at a time.
59
+ *
60
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
61
+ */
62
+ export declare class PasswordItem {
63
+ private readonly client;
64
+ /** The team that owns the item. */
65
+ readonly team: Team;
66
+ private readonly wake;
67
+ /** The item's id. */
68
+ readonly id: string;
69
+ private hit?;
70
+ private constructor();
71
+ /** A handle to an item from a search hit or write result. */
72
+ static fromHit(client: MacroClient, team: Team, wake: AgentWake, hit: PasswordAgentSearchHit): PasswordItem;
73
+ /** A handle to an item by id, without metadata until a write returns it. */
74
+ static byId(client: MacroClient, team: Team, wake: AgentWake, id: string): PasswordItem;
75
+ /** Display name, when this handle came from a search or write. */
76
+ get name(): string | undefined;
77
+ /** Stored kind, when known. */
78
+ get kind(): PasswordItemKind | undefined;
79
+ /** Website URL, when known. */
80
+ get url(): string | undefined;
81
+ /** Committed version, when known. */
82
+ get version(): number | undefined;
83
+ /** The agent's access when this handle was read; recomputed by every call. */
84
+ get access(): PasswordAgentItemAccess | undefined;
85
+ private path;
86
+ /** Disclose one field for copying. Values never belong in model context. */
87
+ disclose(selector: SecretSelector, opts?: {
88
+ /** Fail with `version_conflict` unless this is the committed version. */
89
+ expectedVersion?: number;
90
+ }): Promise<DisclosedSecret>;
91
+ /** The current verification code of a login or verification-code item. */
92
+ verificationCode(): Promise<VerificationCode>;
93
+ /**
94
+ * Replace supplied fields of a login or API item at `expectedVersion`.
95
+ * Notes and custom fields are kept exactly. A retry with the same
96
+ * `operationId` returns the accepted result.
97
+ */
98
+ update(opts: {
99
+ expectedVersion: number;
100
+ secret?: PasswordAgentSecretPatch;
101
+ name?: string;
102
+ /** `null` clears the URL. */
103
+ url?: string | null;
104
+ /** UUIDv7 stable across retries of this update; generated when omitted. */
105
+ operationId?: string;
106
+ }): Promise<PasswordItem>;
107
+ /** Enroll a base32 verification-code seed on a login item this agent created. */
108
+ setVerificationSeed(opts: {
109
+ seed: string;
110
+ expectedVersion: number;
111
+ /** UUIDv7 naming this enrollment, stable across retries; generated when omitted. */
112
+ operationId?: string;
113
+ }): Promise<void>;
114
+ /** Ask the item's managers for access; deduplicated while pending. */
115
+ requestAccess(permission: PasswordPermission): Promise<AgentAccessRequest>;
116
+ /** This agent's own request state for the item. */
117
+ accessRequest(): Promise<AgentAccessRequest>;
118
+ }
@@ -0,0 +1,45 @@
1
+ import type { PasswordAgentCreateSecret } from '../../../generated/storage/types.gen';
2
+ import { type IterationOptions } from '../../utils';
3
+ import type { MacroClient } from '../../utils/client';
4
+ import type { Team } from '../teams/team';
5
+ import { type AgentWake, PasswordItem } from './item';
6
+ /**
7
+ * Team vault access for the authenticated agent. Only the agent's own API key
8
+ * can use it; human vault routes are not part of the SDK.
9
+ *
10
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
11
+ */
12
+ export declare class PasswordNamespace {
13
+ private readonly client;
14
+ constructor(client: MacroClient);
15
+ /** The team's vault as this agent sees it during one wake. */
16
+ forAgent(team: Team, wake: AgentWake): AgentVault;
17
+ }
18
+ /**
19
+ * One team's vault for one agent wake. Every call recomputes the agent's
20
+ * current access.
21
+ *
22
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
23
+ */
24
+ export declare class AgentVault {
25
+ private readonly client;
26
+ /** The team that owns the vault. */
27
+ readonly team: Team;
28
+ private readonly wake;
29
+ constructor(client: MacroClient,
30
+ /** The team that owns the vault. */
31
+ team: Team, wake: AgentWake);
32
+ /** Items the agent may use or request, newest first, metadata only; `maxItems` caps the total. */
33
+ search(query?: string, opts?: IterationOptions): AsyncGenerator<PasswordItem>;
34
+ /**
35
+ * Create a login or API item owned by the team and usable by this agent at
36
+ * once. A retry with the same `operationId` returns the same item.
37
+ */
38
+ create(opts: {
39
+ name: string;
40
+ url?: string;
41
+ secret: PasswordAgentCreateSecret;
42
+ /** UUIDv7 stable across retries; generated when omitted. */
43
+ operationId?: string;
44
+ }): Promise<PasswordItem>;
45
+ }
@@ -37,7 +37,7 @@ export declare class ProjectNamespace {
37
37
  parent?: Project;
38
38
  }): Promise<Project>;
39
39
  /**
40
- * Search projects by name and content, most relevant first, auto-paginated.
40
+ * Search projects by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
41
41
  *
42
42
  * @readonly
43
43
  */
@@ -1,5 +1,6 @@
1
1
  import type { GetProjectContentHandlerResponses, GetProjectHandlerResponses } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import { PropertiedEntity } from '../entity';
4
5
  import { EntityAccess } from '../sharing/access';
5
6
  import { type SharePermissionOptions } from '../sharing/permissions';
@@ -32,6 +33,15 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
32
33
  readonly access: EntityAccess;
33
34
  /** Favorites identify projects as `project`. */
34
35
  readonly entityType = "project";
36
+ /**
37
+ * Share this project with a channel's current members, as posting it in the
38
+ * channel does. The caller must be in the channel and able to share the
39
+ * project; sharing again changes nothing.
40
+ *
41
+ * @write
42
+ * @idempotent
43
+ */
44
+ shareWithChannel(channel: Channel): Promise<void>;
35
45
  /** The properties service identifies projects as `PROJECT`. */
36
46
  protected readonly propertyEntityType = "PROJECT";
37
47
  protected fetch(): Promise<ProjectDetail>;
@@ -92,7 +102,7 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
92
102
  * @idempotent
93
103
  */
94
104
  restore(): Promise<void>;
95
- /** Search projects by name and content, most relevant first, auto-paginated. */
105
+ /** Search projects by name and content, most relevant first, auto-paginated; `maxItems` caps the total. */
96
106
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Project, any, any>;
97
107
  }
98
108
  export {};
@@ -33,7 +33,7 @@ export declare class ReferralNamespace {
33
33
  *
34
34
  * @param email - The address to invite.
35
35
  *
36
- * @destructive
36
+ * @send
37
37
  * @openworld
38
38
  */
39
39
  invite(email: string): Promise<void>;
@@ -1,7 +1,8 @@
1
- import type { RoutineCheck, SuggestOutcome, Surface } from '../../../generated/scheduled-action/types.gen';
1
+ import type { RoutineCheck, RoutineSuggestionCard, SuggestOutcome, Surface } from '../../../generated/scheduled-action/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { MacroEntityType } from '../entity';
4
4
  import { Routine, type RoutineOptions } from './routine';
5
+ import { RoutineSuggestion } from './suggestion';
5
6
  /** Something created for a routine to use: any handle with an entity type, such as a `Database`. */
6
7
  export interface CreatedEntity {
7
8
  readonly id: string;
@@ -18,6 +19,7 @@ export interface CreatedEntity {
18
19
  * - "Remind me", "every Monday", "tomorrow at 9" and "whenever something happens" ask for a routine: work that runs later, as the user, after this conversation ends. A meeting with other people is a calendar event, not a routine.
19
20
  * - A routine's run never sees this conversation. Write its instructions to stand alone: what to do, the items involved by id or link, absolute dates, and where to report the result.
20
21
  * - Before creating one, look for a routine of the user's that already does this, and update it instead of adding a second.
22
+ * - A routine created by a routine's run, from its code or its Ask AI step, is that routine's sub-routine: it is listed under it, pauses and is deleted with it, and `list()` leaves it out unless asked. A routine has at most 50 active sub-routines (one-time ones that have run don't count); creating another is refused. When a run may create the same routine again, pass a `key` so the second create updates the first instead of adding a duplicate.
21
23
  *
22
24
  * ### Writing one
23
25
  *
@@ -49,11 +51,13 @@ export declare class RoutineNamespace {
49
51
  /** Construct a lazy routine handle. */
50
52
  byId(id: string): Routine;
51
53
  /**
52
- * Create a routine: one agent task (`prompt`, with `model`, `agent`, or
53
- * both), or code and Ask AI `steps`. Set `dangerouslyOperateAsUser` only
54
- * when the user explicitly asked for it to act, send or post as them. To
55
- * check on something later, such as a spawned session or a long job, create
56
- * a routine instead of waiting in a program. A cron `schedule` has 6 fields
54
+ * Create a routine from `steps`: code steps and at most one Ask AI
55
+ * (`agent`) step. The older single agent task (`prompt`, with `model`,
56
+ * `agent`, or both) still saves and runs as one Ask AI step; write new
57
+ * routines as steps. Set `dangerouslyOperateAsUser` only when the user
58
+ * explicitly asked for it to act, send or post as them. To check on
59
+ * something later, such as a spawned session or a long job, create a
60
+ * routine instead of waiting in a program. A cron `schedule` has 6 fields
57
61
  * (second minute hour day-of-month month day-of-week) or 7 with a year; a
58
62
  * 7-field schedule that names one date runs once. A code step's `source`
59
63
  * exports `async function main({ macro, run, trigger, steps, knobs })` and
@@ -61,26 +65,41 @@ export declare class RoutineNamespace {
61
65
  * `MacroApiError` whose message says what the server refused, including
62
66
  * type-check errors.
63
67
  *
68
+ * Inside a routine's run, the new routine is that routine's sub-routine
69
+ * ({@link Routine.parent}). Pass `key` there to name it: creating with the
70
+ * same key again updates that sub-routine instead of adding another, so a
71
+ * run that repeats is safe. Without a key every create adds a routine, and
72
+ * the 51st active sub-routine is refused. Outside a routine's run a key is
73
+ * rejected.
74
+ *
64
75
  * @example
65
76
  * // Every ten minutes, in New York time.
66
77
  * const routine = await macro.routines.create({
67
78
  * name: 'Check the import',
68
- * prompt: 'Read the import task and post its status in the channel.',
69
- * userPrompt: 'Check on the import every ten minutes.',
70
- * model: 'anthropic/claude-sonnet-5-5',
71
79
  * trigger: {
72
80
  * type: 'cron',
73
81
  * schedule: '0 0/10 * * * *',
74
82
  * timezone: 'America/New_York',
75
83
  * },
84
+ * steps: [
85
+ * {
86
+ * type: 'agent',
87
+ * instructions: 'Read the import task and post its status in the channel.',
88
+ * model: 'anthropic/claude-sonnet-5-5',
89
+ * },
90
+ * ],
76
91
  * });
77
92
  * // Once, at 14:30 on 3 November 2027.
78
93
  * await macro.routines.create({
79
94
  * name: 'Follow up on the review',
80
- * prompt: 'Read the review session and summarize its outcome.',
81
- * userPrompt: 'Follow up on the review on 3 November 2027.',
82
- * model: 'anthropic/claude-sonnet-5-5',
83
95
  * trigger: { type: 'cron', schedule: '0 30 14 3 11 * 2027', timezone: 'UTC' },
96
+ * steps: [
97
+ * {
98
+ * type: 'agent',
99
+ * instructions: 'Read the review session and summarize its outcome.',
100
+ * model: 'anthropic/claude-sonnet-5-5',
101
+ * },
102
+ * ],
84
103
  * });
85
104
  * // A code step that posts in a channel, disabled until turned on. The
86
105
  * // user asked for the post to come from them.
@@ -99,10 +118,31 @@ export declare class RoutineNamespace {
99
118
  * ],
100
119
  * dangerouslyOperateAsUser: true,
101
120
  * });
121
+ * // In a routine's code step: one follow-up per task, however often it runs.
122
+ * await macro.routines.create(
123
+ * {
124
+ * name: `Check on ${taskName}`,
125
+ * trigger: { type: 'once', at: tomorrow },
126
+ * steps: [
127
+ * {
128
+ * type: 'agent',
129
+ * instructions: `Read task ${taskId} and post its status in the channel.`,
130
+ * model: 'anthropic/claude-sonnet-5-5',
131
+ * },
132
+ * ],
133
+ * },
134
+ * { key: `check-${taskId}` },
135
+ * );
102
136
  *
103
137
  * @write
104
138
  */
105
- create(options: RoutineOptions): Promise<Routine>;
139
+ create(options: RoutineOptions, extra?: {
140
+ /**
141
+ * Names the routine among its parent's sub-routines, up to 200
142
+ * characters. Only inside a routine's run.
143
+ */
144
+ key?: string;
145
+ }): Promise<Routine>;
106
146
  /**
107
147
  * Check a routine without saving it: the checks `create` makes, including
108
148
  * type-checking its code steps, with nothing saved. Returns whether it
@@ -127,15 +167,16 @@ export declare class RoutineNamespace {
127
167
  created?: CreatedEntity[];
128
168
  }): Promise<RoutineCheck>;
129
169
  /**
130
- * Suggest a routine to the user. Only a routine suggestion session may
170
+ * Suggest a routine to the user. Only a routines generation session may
131
171
  * call this; any other session gets a 403. Suggest a catalog routine by
132
172
  * `key` with `knobs`, or a `routine` the catalog lacks, written as `check`
133
173
  * takes it and checked the same way. `surfaces` are the parts of the app
134
174
  * whose sidebar shows it, best fit first; `reason` is one line, shown to
135
175
  * the user, naming no one's email address; `keepProbability` is the
136
- * chance, from 0 to 1, that the user keeps it on. Returns whether it was
137
- * kept (`ok`) and, when not, the `problems` to fix before suggesting it
138
- * again.
176
+ * chance, from 0 to 1, that the user keeps it on. A drafted `routine`
177
+ * also shows in the user's Suggestions feed, as its `card` says; a catalog
178
+ * routine takes no `card`. Returns whether it was kept (`ok`) and, when
179
+ * not, the `problems` to fix before suggesting it again.
139
180
  *
140
181
  * @example
141
182
  * const outcome = await macro.routines.suggest({
@@ -164,13 +205,35 @@ export declare class RoutineNamespace {
164
205
  reason: string;
165
206
  surfaces: Surface[];
166
207
  keepProbability: number;
208
+ /** How it shows in the user's Suggestions feed: a short title, an importance from 0 to 100, and fitting categories. */
209
+ card: RoutineSuggestionCard;
167
210
  }): Promise<SuggestOutcome>;
168
211
  /**
169
- * List routines, optionally including event triggers.
212
+ * Every routine suggestion AI made for the user, open or not, and how
213
+ * many more this session may hand back. Only a routines generation
214
+ * session may call this. Retire with `suggestion.retire(reason)` what no
215
+ * longer fits; suggestions are never rewritten.
216
+ *
217
+ * @mcp-exclude only a routines generation session may call it
218
+ */
219
+ review(): Promise<{
220
+ suggestions: RoutineSuggestion[];
221
+ keptLeft: number;
222
+ }>;
223
+ /**
224
+ * List the user's top-level routines, as their Routines list shows them:
225
+ * sub-routines, which other routines' runs created, are left out. Pass
226
+ * `parent` for one routine's sub-routines (its newest finished one-time
227
+ * ones included), or `includeChildren` to add active sub-routines; each
228
+ * sub-routine names its {@link Routine.parent} and
229
+ * {@link Routine.createdByRun}. `includeEvents` adds event-triggered
230
+ * routines.
170
231
  *
171
232
  * @readonly
172
233
  */
173
234
  list(options?: {
174
235
  includeEvents?: boolean;
236
+ includeChildren?: boolean;
237
+ parent?: Routine;
175
238
  }): Promise<Routine[]>;
176
239
  }
@@ -1,4 +1,5 @@
1
1
  import type { ActionTrigger, CodeStep, EventFilter, RoutineModelId, RoutineTask, RoutineTemplate as RoutineTemplateRecord, RoutineTrigger, RunVisibility, ScheduledActionResponse, TemplateVariable } from '../../../generated/scheduled-action/types.gen';
2
+ import type { EntityAppearance } from '../../../generated/storage/types.gen';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { AgentSession } from '../agent-sessions/agent-session';
4
5
  import type { Agent } from '../agents/agent';
@@ -69,7 +70,10 @@ interface RoutineCommonOptions {
69
70
  */
70
71
  runVisibility?: RunVisibility;
71
72
  }
72
- /** A routine that hands each run to one model or agent. */
73
+ /**
74
+ * A routine that hands each run to one model or agent: the older form, which
75
+ * runs as one Ask AI step. Write new routines as {@link StepsRoutineOptions}.
76
+ */
73
77
  export interface AgentRoutineOptions extends RoutineCommonOptions {
74
78
  /** Instructions delivered to the agent. */
75
79
  prompt: string;
@@ -106,7 +110,7 @@ export interface StepsRoutineOptions extends RoutineCommonOptions {
106
110
  model?: never;
107
111
  agent?: never;
108
112
  }
109
- /** Configuration of a routine: one agent task, or code and Ask AI steps. */
113
+ /** Configuration of a routine: code and Ask AI steps, or the older single agent task. */
110
114
  export type RoutineOptions = AgentRoutineOptions | StepsRoutineOptions;
111
115
  /** A scheduled or event-triggered agent task. */
112
116
  export declare class Routine extends MacroEntity<ScheduledActionResponse> {
@@ -129,6 +133,15 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
129
133
  protected fetch(): Promise<ScheduledActionResponse>;
130
134
  /** Routine name. */
131
135
  readonly name: () => Promise<string>;
136
+ /** Shared icon and color overrides. */
137
+ readonly appearance: () => Promise<import("../../../generated/scheduled-action").EntityAppearance | undefined>;
138
+ /**
139
+ * Replace shared appearance without rescheduling. Pass {} to reset both overrides.
140
+ *
141
+ * @write
142
+ * @idempotent
143
+ */
144
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
132
145
  /** Configured triggers. */
133
146
  readonly trigger: () => Promise<ActionTrigger>;
134
147
  /** Whether the routine is enabled. */
@@ -143,6 +156,33 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
143
156
  readonly owner: () => Promise<User>;
144
157
  /** The shared routine whose template this routine was activated from. */
145
158
  readonly sourceTemplate: () => Promise<Routine | undefined>;
159
+ /**
160
+ * The routine this one follows, when one of that routine's runs created
161
+ * it: pausing the parent pauses it and deleting the parent deletes it.
162
+ * `undefined` for a top-level routine.
163
+ */
164
+ readonly parent: () => Promise<Routine | undefined>;
165
+ /**
166
+ * The run that created this sub-routine, by the id its history record
167
+ * has once that run ends. `undefined` for a top-level routine.
168
+ */
169
+ readonly createdByRun: () => Promise<RoutineRun | undefined>;
170
+ /** The key this sub-routine was created under, if its creator gave one. */
171
+ readonly key: () => Promise<string | undefined>;
172
+ /**
173
+ * This routine's sub-routines: the active ones and its newest finished
174
+ * one-time ones.
175
+ *
176
+ * @readonly
177
+ */
178
+ children(): Promise<Routine[]>;
179
+ /**
180
+ * Keep this sub-routine as the user's own routine: it moves to their main
181
+ * list and no longer pauses or is deleted with its parent.
182
+ *
183
+ * @write
184
+ */
185
+ keepAsOwn(): Promise<void>;
146
186
  /**
147
187
  * This routine's shared template, or `undefined` when it isn't shared.
148
188
  *
@@ -211,6 +251,22 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
211
251
  */
212
252
  delete(): Promise<void>;
213
253
  }
254
+ /**
255
+ * One run of a routine, by the id of its history record.
256
+ *
257
+ * @mcp-exclude Read from a sub-routine's record; no call takes one.
258
+ */
259
+ export declare class RoutineRun {
260
+ /** The run's id, which its {@link RoutineExecution} has once it ends. */
261
+ readonly id: string;
262
+ constructor(
263
+ /** The run's id, which its {@link RoutineExecution} has once it ends. */
264
+ id: string);
265
+ /** Serialize the run's identity. */
266
+ toJSON(): {
267
+ id: string;
268
+ };
269
+ }
214
270
  /**
215
271
  * A routine shared as a template, which people activate as their own routine.
216
272
  *
@@ -245,12 +301,16 @@ export declare class RoutineExecution {
245
301
  /** Parent routine. */
246
302
  readonly routine: Routine;
247
303
  /** Execution snapshot. */
248
- readonly record: import('../../../generated/scheduled-action/types.gen').ActionExecutionRecord;
304
+ readonly record: import('../../../generated/scheduled-action/types.gen').ExecutionRecordResponse;
305
+ /** The sub-routines this run created that still follow the routine. */
306
+ readonly created: Routine[];
249
307
  constructor(
250
308
  /** Parent routine. */
251
309
  routine: Routine,
252
310
  /** Execution snapshot. */
253
- record: import('../../../generated/scheduled-action/types.gen').ActionExecutionRecord);
311
+ record: import('../../../generated/scheduled-action/types.gen').ExecutionRecordResponse,
312
+ /** The sub-routines this run created that still follow the routine. */
313
+ created?: Routine[]);
254
314
  /** Execution identity, when assigned. */
255
315
  get id(): string | undefined;
256
316
  /** Serialize without the authenticated client. */
@@ -265,6 +325,7 @@ export declare class RoutineExecution {
265
325
  [key: string]: unknown;
266
326
  };
267
327
  start_time: string;
328
+ created?: Array<import("../../../generated/scheduled-action").CreatedRoutine>;
268
329
  routine: string;
269
330
  };
270
331
  }