@macro-inc/sdk 0.0.1 → 0.2.2

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 (165) hide show
  1. package/README.md +628 -21
  2. package/dist/{chunk-5HAKQN23.js → chunk-7LVVPVNT.js} +70 -57
  3. package/dist/{chunk-JXIQT5TH.js → chunk-7YJ6Y7HJ.js} +234 -16
  4. package/dist/chunk-LMJW65ML.js +836 -0
  5. package/dist/{chunk-SGAHIERJ.js → chunk-OGE7WXJE.js} +16 -0
  6. package/dist/chunk-PRUFPW3B.js +943 -0
  7. package/dist/{chunk-CTKR64MY.js → chunk-QVBNNMQS.js} +242 -367
  8. package/dist/{chunk-QNUS5BC5.js → chunk-SUINKDXF.js} +30 -84
  9. package/dist/{chunk-77EI4LSQ.js → chunk-ZQXOHNDB.js} +1518 -386
  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 +174 -4
  13. package/dist/generated/agent-harness/types.gen.d.ts +2511 -189
  14. package/dist/generated/auth/index.d.ts +1 -1
  15. package/dist/generated/auth/index.js +1 -1
  16. package/dist/generated/auth/sdk.gen.d.ts +106 -8
  17. package/dist/generated/auth/types.gen.d.ts +1473 -116
  18. package/dist/generated/calendar/client/client.gen.d.ts +2 -0
  19. package/dist/generated/calendar/client/index.d.ts +10 -0
  20. package/dist/generated/calendar/client/types.gen.d.ts +120 -0
  21. package/dist/generated/calendar/client/utils.gen.d.ts +37 -0
  22. package/dist/generated/calendar/client.gen.d.ts +12 -0
  23. package/dist/generated/calendar/core/auth.gen.d.ts +25 -0
  24. package/dist/generated/calendar/core/bodySerializer.gen.d.ts +25 -0
  25. package/dist/generated/calendar/core/params.gen.d.ts +43 -0
  26. package/dist/generated/calendar/core/pathSerializer.gen.d.ts +33 -0
  27. package/dist/generated/calendar/core/queryKeySerializer.gen.d.ts +18 -0
  28. package/dist/generated/calendar/core/serverSentEvents.gen.d.ts +71 -0
  29. package/dist/generated/calendar/core/types.gen.d.ts +83 -0
  30. package/dist/generated/calendar/core/utils.gen.d.ts +19 -0
  31. package/dist/generated/calendar/index.d.ts +2 -0
  32. package/dist/generated/calendar/index.js +6 -0
  33. package/dist/generated/calendar/sdk.gen.d.ts +95 -0
  34. package/dist/generated/calendar/types.gen.d.ts +1091 -0
  35. package/dist/generated/cognition/index.d.ts +1 -1
  36. package/dist/generated/cognition/index.js +1 -1
  37. package/dist/generated/cognition/sdk.gen.d.ts +6 -1
  38. package/dist/generated/cognition/types.gen.d.ts +304 -36
  39. package/dist/generated/connection/types.gen.d.ts +1 -1
  40. package/dist/generated/email/index.d.ts +1 -1
  41. package/dist/generated/email/index.js +1 -1
  42. package/dist/generated/email/sdk.gen.d.ts +32 -27
  43. package/dist/generated/email/types.gen.d.ts +586 -409
  44. package/dist/generated/notification/index.d.ts +1 -1
  45. package/dist/generated/notification/types.gen.d.ts +384 -19
  46. package/dist/generated/properties/types.gen.d.ts +8 -5
  47. package/dist/generated/scheduled-action/index.d.ts +1 -1
  48. package/dist/generated/scheduled-action/index.js +3 -842
  49. package/dist/generated/scheduled-action/sdk.gen.d.ts +3 -1
  50. package/dist/generated/scheduled-action/types.gen.d.ts +277 -41
  51. package/dist/generated/search/index.d.ts +1 -1
  52. package/dist/generated/search/types.gen.d.ts +262 -43
  53. package/dist/generated/storage/index.d.ts +1 -1
  54. package/dist/generated/storage/index.js +1 -1
  55. package/dist/generated/storage/sdk.gen.d.ts +678 -107
  56. package/dist/generated/storage/types.gen.d.ts +14827 -5995
  57. package/dist/generated/unfurl/index.d.ts +1 -1
  58. package/dist/generated/unfurl/index.js +3 -832
  59. package/dist/generated/unfurl/types.gen.d.ts +20 -0
  60. package/dist/src/config.d.ts +33 -13
  61. package/dist/src/entities/agent-sessions/agent-session.d.ts +150 -6
  62. package/dist/src/entities/agent-sessions/code-execution.d.ts +43 -0
  63. package/dist/src/entities/agent-sessions/conversation.d.ts +54 -0
  64. package/dist/src/entities/agent-sessions/namespace.d.ts +23 -5
  65. package/dist/src/entities/agent-sessions/queued-action.d.ts +46 -0
  66. package/dist/src/entities/agent-sessions/review.d.ts +107 -0
  67. package/dist/src/entities/agent-sessions/tool-approval.d.ts +21 -0
  68. package/dist/src/entities/agents/agent.d.ts +47 -0
  69. package/dist/src/entities/agents/namespace.d.ts +13 -0
  70. package/dist/src/entities/ai/namespace.d.ts +24 -0
  71. package/dist/src/entities/api-keys/api-key.d.ts +17 -0
  72. package/dist/src/entities/api-keys/namespace.d.ts +18 -0
  73. package/dist/src/entities/calendar/calendar.d.ts +35 -0
  74. package/dist/src/entities/calendar/event.d.ts +123 -0
  75. package/dist/src/entities/calendar/event.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/namespace.d.ts +111 -0
  77. package/dist/src/entities/calendar/replacement.d.ts +15 -0
  78. package/dist/src/entities/calls/call-record.d.ts +62 -6
  79. package/dist/src/entities/calls/message.d.ts +33 -0
  80. package/dist/src/entities/channels/activity.d.ts +24 -0
  81. package/dist/src/entities/channels/channel.d.ts +44 -3
  82. package/dist/src/entities/channels/labels.d.ts +39 -0
  83. package/dist/src/entities/channels/message.d.ts +9 -17
  84. package/dist/src/entities/channels/namespace.d.ts +6 -0
  85. package/dist/src/entities/channels/picture.d.ts +11 -0
  86. package/dist/src/entities/channels/post.d.ts +1 -1
  87. package/dist/src/entities/channels/thread.d.ts +5 -0
  88. package/dist/src/entities/chats/chat.d.ts +11 -1
  89. package/dist/src/entities/chats/generation.d.ts +46 -0
  90. package/dist/src/entities/crm/comment.d.ts +55 -34
  91. package/dist/src/entities/crm/company.d.ts +42 -10
  92. package/dist/src/entities/crm/contact.d.ts +42 -10
  93. package/dist/src/entities/crm/namespace.d.ts +18 -1
  94. package/dist/src/entities/crm/pipeline.d.ts +122 -0
  95. package/dist/src/entities/crm/pipelines.d.ts +14 -0
  96. package/dist/src/entities/databases/column.d.ts +75 -0
  97. package/dist/src/entities/databases/database.d.ts +272 -0
  98. package/dist/src/entities/databases/namespace.d.ts +21 -0
  99. package/dist/src/entities/databases/query.d.ts +86 -0
  100. package/dist/src/entities/databases/row.d.ts +27 -0
  101. package/dist/src/entities/databases/table.d.ts +61 -0
  102. package/dist/src/entities/databases/view.d.ts +40 -0
  103. package/dist/src/entities/databases/webhook.d.ts +32 -0
  104. package/dist/src/entities/documents/anchor.d.ts +29 -0
  105. package/dist/src/entities/documents/comment.d.ts +25 -22
  106. package/dist/src/entities/documents/document.d.ts +60 -12
  107. package/dist/src/entities/documents/namespace.d.ts +30 -0
  108. package/dist/src/entities/documents/version.d.ts +22 -0
  109. package/dist/src/entities/email/draft.d.ts +79 -0
  110. package/dist/src/entities/email/filter.d.ts +34 -0
  111. package/dist/src/entities/email/link.d.ts +6 -4
  112. package/dist/src/entities/email/message.d.ts +12 -1
  113. package/dist/src/entities/email/namespace.d.ts +34 -1
  114. package/dist/src/entities/email/thread.d.ts +23 -1
  115. package/dist/src/entities/entity-mentions/mention.d.ts +16 -0
  116. package/dist/src/entities/entity-mentions/namespace.d.ts +12 -0
  117. package/dist/src/entities/entity.d.ts +7 -0
  118. package/dist/src/entities/favorites/namespace.d.ts +14 -2
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +2 -0
  120. package/dist/src/entities/foreign/namespace.d.ts +40 -0
  121. package/dist/src/entities/forms/form.d.ts +227 -0
  122. package/dist/src/entities/forms/namespace.d.ts +18 -0
  123. package/dist/src/entities/forms/question.d.ts +37 -0
  124. package/dist/src/entities/forms/response.d.ts +32 -0
  125. package/dist/src/entities/forms/section.d.ts +19 -0
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +12 -0
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +52 -0
  128. package/dist/src/entities/harnesses/harness.d.ts +19 -0
  129. package/dist/src/entities/harnesses/namespace.d.ts +33 -0
  130. package/dist/src/entities/harnesses/pairing.d.ts +39 -0
  131. package/dist/src/entities/initiatives/initiative.d.ts +50 -0
  132. package/dist/src/entities/initiatives/namespace.d.ts +13 -0
  133. package/dist/src/entities/meetings/meeting.d.ts +38 -0
  134. package/dist/src/entities/meetings/namespace.d.ts +18 -0
  135. package/dist/src/entities/messages/thread.d.ts +101 -0
  136. package/dist/src/entities/notifications/notification.d.ts +6 -3
  137. package/dist/src/entities/notifications/notification.test.d.ts +1 -0
  138. package/dist/src/entities/projects/project.d.ts +7 -0
  139. package/dist/src/entities/reference.d.ts +82 -0
  140. package/dist/src/entities/routines/namespace.d.ts +15 -0
  141. package/dist/src/entities/routines/routine.d.ts +115 -0
  142. package/dist/src/entities/sharing/access.d.ts +65 -0
  143. package/dist/src/entities/sharing/permissions.d.ts +13 -0
  144. package/dist/src/entities/tasks/namespace.d.ts +4 -0
  145. package/dist/src/entities/tasks/task.d.ts +6 -0
  146. package/dist/src/entities/unfurls/namespace.d.ts +10 -0
  147. package/dist/src/entities/webhooks/webhook.d.ts +3 -1
  148. package/dist/src/entities/workspace/items.d.ts +7 -0
  149. package/dist/src/entities/workspace/namespace.d.ts +83 -0
  150. package/dist/src/entities/workspace/query.d.ts +12 -0
  151. package/dist/src/entities/workspace/types.d.ts +96 -0
  152. package/dist/src/events/hydrate/agentSession.d.ts +192 -0
  153. package/dist/src/events/hydrate/channel.d.ts +2 -39
  154. package/dist/src/events/hydrate/message.d.ts +70 -0
  155. package/dist/src/events/receiver.d.ts +57 -19
  156. package/dist/src/events/types.d.ts +3 -1
  157. package/dist/src/macro.d.ts +80 -3
  158. package/dist/src/macro.js +8832 -2784
  159. package/dist/src/utils/activity.d.ts +11 -0
  160. package/dist/src/utils/activity.test.d.ts +1 -0
  161. package/dist/src/utils/client.d.ts +10 -1
  162. package/dist/src/utils/concurrency.d.ts +5 -0
  163. package/dist/src/utils/index.d.ts +1 -0
  164. package/dist/src/utils/pagination.d.ts +9 -4
  165. package/package.json +11 -3
@@ -26,6 +26,14 @@ export type GetUnfurlResponse = {
26
26
  * The page description (from `og:description`), if any.
27
27
  */
28
28
  description?: string | null;
29
+ /**
30
+ * The type of embeddable content, if the URL supports iframe embedding.
31
+ */
32
+ embed_type?: UnfurlEmbedType;
33
+ /**
34
+ * The iframe-embeddable URL for services like Loom or Supercut.
35
+ */
36
+ embed_url?: string | null;
29
37
  /**
30
38
  * The page's favicon URL, if any.
31
39
  */
@@ -46,11 +54,23 @@ export type GetUnfurlResponse = {
46
54
  export type ProxyParams = {
47
55
  url: string;
48
56
  };
57
+ /**
58
+ * The type of embeddable content for services that support iframe embedding.
59
+ */
60
+ export type UnfurlEmbedType = 'None' | 'Video';
49
61
  export type Vec = Array<null | {
50
62
  /**
51
63
  * The page description (from `og:description`), if any.
52
64
  */
53
65
  description?: string | null;
66
+ /**
67
+ * The type of embeddable content, if the URL supports iframe embedding.
68
+ */
69
+ embed_type?: UnfurlEmbedType;
70
+ /**
71
+ * The iframe-embeddable URL for services like Loom or Supercut.
72
+ */
73
+ embed_url?: string | null;
54
74
  /**
55
75
  * The page's favicon URL, if any.
56
76
  */
@@ -1,27 +1,38 @@
1
1
  export type Env = 'dev' | 'prod' | 'local';
2
2
  /** The backend services the SDK talks to. Note `search` and `properties` are
3
3
  * served on the storage host, so they point there. */
4
- export type ServiceName = 'agent-harness' | 'storage' | 'auth' | 'email' | 'cognition' | 'notification' | 'properties' | 'search' | 'scheduled-action' | 'static-files' | 'connection' | 'contacts' | 'unfurl';
4
+ export type ServiceName = 'agent-harness' | 'storage' | 'auth' | 'email' | 'calendar' | 'cognition' | 'notification' | 'properties' | 'search' | 'scheduled-action' | 'static-files' | 'connection' | 'contacts' | 'unfurl';
5
5
  export declare const WEB_APP_URLS: Record<Env, string>;
6
6
  export declare const HOSTS: Record<Env, Record<ServiceName, string>>;
7
- /** A bearer token, or a (possibly async) function that returns one — the
8
- * function form lets you refresh tokens without reconfiguring. */
7
+ /** A credential string, or a (possibly async) function that returns one. */
9
8
  export type TokenSource = string | (() => string | Promise<string>);
10
9
  /** Access scope for bot-authenticated requests. `user` acts with the
11
10
  * requested-as user's access (requires `requestedAs`); `team` acts with the
12
11
  * bot's owning team's access (team-owned bots only). */
13
12
  export type BotScope = 'user' | 'team';
14
- /** How the SDK authenticates with Macro.
13
+ /**
14
+ * How the SDK authenticates with Macro.
15
15
  *
16
- * - `user`: a human's Macro API token, sent as `Authorization: Bearer`.
17
- * - `bot`: an `mbot_` API key, sent as `x-macro-bot-token` together with
18
- * `x-macro-bot-scope`. When `scope` is omitted it defaults to `user` when
19
- * `requestedAs` is set (user scope requires an acting user) and `team`
20
- * otherwise.
16
+ * A user has exactly one of two credential fields.
17
+ *
18
+ * - `token`: a bearer token, or a `mak_` API key. The SDK picks the header
19
+ * from the prefix at send time.
20
+ * - `apiKey`: a Settings → API Keys key, always sent as
21
+ * `x-macro-user-api-key`. Not prefix-checked, so keys that predate the
22
+ * `mak_` prefix work here.
23
+ *
24
+ * A bot uses an `mbot_` token as `x-macro-bot-token` plus
25
+ * `x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and
26
+ * `team` otherwise.
21
27
  */
22
28
  export type MacroAuth = {
23
29
  type: 'user';
24
30
  token: TokenSource;
31
+ apiKey?: never;
32
+ } | {
33
+ type: 'user';
34
+ apiKey: string;
35
+ token?: never;
25
36
  } | {
26
37
  type: 'bot';
27
38
  token: TokenSource;
@@ -29,10 +40,14 @@ export type MacroAuth = {
29
40
  };
30
41
  /** Options passed to `new Macro(opts)` and stored on `MacroClient`. */
31
42
  export interface MacroOpts {
32
- /** How to authenticate. Takes precedence over `token`. Falls back to the
33
- * MACRO_API_KEY (user auth) or MACRO_BOT_TOKEN (bot auth) env var. */
43
+ /** Optional generated API operation events; excludes arguments, URLs and response data. */
44
+ onRequest?: (event: import('./utils/activity').RequestActivity) => void;
45
+ /** How to authenticate. Takes precedence over `token`. Falls back to
46
+ * `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN`
47
+ * (bot). */
34
48
  auth?: MacroAuth;
35
- /** Shorthand for `auth: { type: 'user', token }`. */
49
+ /** Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API
50
+ * key (`mak_…`) or a bearer token. */
36
51
  token?: TokenSource;
37
52
  /** Which Macro environment to talk to. Falls back to the MACRO_ENV env
38
53
  * var, then `'prod'`. */
@@ -41,7 +56,12 @@ export interface MacroOpts {
41
56
  hosts?: Partial<Record<ServiceName, string>>;
42
57
  /** Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. */
43
58
  webAppUrl?: string;
44
- /** Signing secret for verifying incoming webhooks. Falls back to MACRO_WEBHOOK_SECRET. */
59
+ /**
60
+ * Signing secret for verifying incoming persisted-webhook deliveries.
61
+ * Required only for `macro.events.webhook()` / `macro.events.handle()`.
62
+ * SSE via `macro.events.listen()` uses the API token and does not need
63
+ * this. Falls back to MACRO_WEBHOOK_SECRET.
64
+ */
45
65
  webhookSecret?: string;
46
66
  wsVerify?: string;
47
67
  /** User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on
@@ -1,17 +1,92 @@
1
- import type { AgentAction, AgentActionId, AgentSessionLogResponse, AgentSessionResponse, SandboxSize } from '../../../generated/agent-harness/types.gen';
1
+ import type { AgentAction, AgentSessionChangesResponse, AgentSessionLogResponse, AgentSessionResponse, CodingPreferencesBody, ControlResponse, PromptAttachment, PullRequestLinkSource, SandboxSize } from '../../../generated/agent-harness/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { MacroEntity } from '../entity';
4
+ import { EntityAccess } from '../sharing/access';
5
+ import { type SharePermissionOptions } from '../sharing/permissions';
6
+ import { User } from '../users/user';
7
+ import { CodeExecution } from './code-execution';
8
+ import { QueuedAction } from './queued-action';
9
+ import { type CreateReviewOptions, SessionReview } from './review';
10
+ import { ToolApproval } from './tool-approval';
11
+ /** A GitHub pull request linked to a session. */
12
+ export type SessionPullRequest = {
13
+ /** The pull request's `owner/repo/pull/number` key. */
14
+ githubKey: string;
15
+ /** The pull request's GitHub URL. */
16
+ url: string;
17
+ /** Whether the session's agent opened it or a person linked it. */
18
+ source: PullRequestLinkSource;
19
+ /** Who linked it, for pull requests a person linked. */
20
+ linkedBy?: User;
21
+ /** When it was linked. */
22
+ createdAt: string;
23
+ };
24
+ /** A GitHub repository the caller can point a managed session at. */
25
+ export type SelectableRepository = {
26
+ /** The canonical `https://github.com/owner/name` URL, as `createManaged` takes it. */
27
+ url: string;
28
+ /**
29
+ * The branch its clones check out, and where a session starts unless
30
+ * `createManaged` names another. Absent for a repository with no commits.
31
+ */
32
+ defaultBranch?: string;
33
+ };
34
+ /** What a managed session is created with. */
35
+ export type CreateManagedSessionOptions = {
36
+ /** First prompt to deliver once the session is running. */
37
+ prompt?: string;
38
+ /** Instructions the session's runtime works under, fixed for its life. */
39
+ instructions?: string;
40
+ /**
41
+ * The model the session runs on, instead of its persona's. The session's
42
+ * model from creation, read back as {@link AgentSession.model}.
43
+ */
44
+ model?: string;
45
+ /**
46
+ * The repository the session works on, as one of the URLs
47
+ * {@link AgentSession.repositories} lists for the caller. Omitted, the
48
+ * runtime chooses from the prompt. Honored for Cursor sessions.
49
+ */
50
+ repoUrl?: string;
51
+ /**
52
+ * The branch the session starts on; needs `repoUrl`. Omitted, the
53
+ * repository's default branch.
54
+ */
55
+ repoBranch?: string;
56
+ };
4
57
  /** A managed or externally hosted coding-agent session. */
5
58
  export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
59
+ /** Access requests and direct user grants. */
60
+ readonly access: EntityAccess;
61
+ /** Construct an approval handle scoped to this session. */
62
+ toolApprovalById(id: string): ToolApproval;
63
+ /** Sharing configuration. */
64
+ sharePermissions(): Promise<import("../../../generated/agent-harness").SharePermissionV2>;
65
+ /** Replace sharing grants. */
66
+ updateSharePermissions(options: SharePermissionOptions): Promise<import("../../../generated/agent-harness").SharePermissionV2>;
6
67
  /** A handle to an agent session by id. Details load on first access. */
7
68
  static byId(client: MacroClient, id: string): AgentSession;
8
69
  /** Create a managed session, optionally delivering its first prompt. */
9
- static createManaged(client: MacroClient, opts?: {
10
- prompt?: string;
11
- }): Promise<AgentSession>;
70
+ static createManaged(client: MacroClient, opts?: CreateManagedSessionOptions): Promise<AgentSession>;
71
+ /**
72
+ * The GitHub repositories the caller can hand a managed session: every
73
+ * repository under an installation of Macro's GitHub App they or their
74
+ * teams made, sorted by `owner/name`. Empty when the App is installed
75
+ * nowhere they reach.
76
+ */
77
+ static repositories(client: MacroClient): Promise<SelectableRepository[]>;
78
+ /**
79
+ * Branch names on one repository the caller can start a managed session
80
+ * from, in the order GitHub listed them. Empty when the repository has
81
+ * no commits yet. `repoUrl` is one of the URLs {@link AgentSession.repositories}
82
+ * lists.
83
+ */
84
+ static repositoryBranches(client: MacroClient, repoUrl: string): Promise<string[]>;
12
85
  protected fetch(): Promise<AgentSessionResponse>;
13
86
  /** The session's user-facing display name. */
14
87
  readonly name: () => Promise<string>;
88
+ /** Whether the session is archived and read-only. */
89
+ readonly isArchived: () => Promise<boolean>;
15
90
  /** The model currently configured for the session. */
16
91
  readonly model: () => Promise<string>;
17
92
  /** The agent harness implementation serving the session. */
@@ -20,6 +95,11 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
20
95
  readonly repoUrl: () => Promise<string | undefined>;
21
96
  /** The directory in which the agent harness runs. */
22
97
  readonly workspace: () => Promise<string>;
98
+ /**
99
+ * Instructions the session's runtime works under, when any were stated at
100
+ * creation. Fixed for the session's life.
101
+ */
102
+ readonly instructions: () => Promise<string | undefined>;
23
103
  /** The session's latest runtime status. */
24
104
  readonly status: () => Promise<import("../../../generated/agent-harness").SessionStatusDto>;
25
105
  /** Compute tier of the managed sandbox. */
@@ -28,18 +108,82 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
28
108
  readonly createdAt: () => Promise<string>;
29
109
  /** When the session was last modified. */
30
110
  readonly modifiedAt: () => Promise<string>;
111
+ /**
112
+ * The sessions linked to the GitHub pull request at `url` that the caller
113
+ * can view, oldest link first.
114
+ */
115
+ static forPullRequest(client: MacroClient, url: string): Promise<AgentSession[]>;
116
+ /**
117
+ * The GitHub pull requests linked to this session: the one its agent
118
+ * opened and any a person linked, oldest first.
119
+ */
120
+ pullRequests(): Promise<SessionPullRequest[]>;
121
+ /**
122
+ * Link the GitHub pull request at `url` to this session. Linking one that
123
+ * is already linked changes nothing.
124
+ */
125
+ linkPullRequest(url: string): Promise<void>;
126
+ /**
127
+ * Unlink a GitHub pull request a person linked to this session. The pull
128
+ * request the session's agent opened stays linked.
129
+ */
130
+ unlinkPullRequest(url: string): Promise<void>;
31
131
  /** Rename this session. */
32
132
  rename(name: string): Promise<void>;
133
+ /** Archive this session, making it read-only until unarchived. */
134
+ archive(): Promise<void>;
135
+ /** Restore an archived session so it can be edited and prompted again. */
136
+ unarchive(): Promise<void>;
137
+ private setArchived;
33
138
  /** Resize this session's sandbox and remember the size as the owner's default. */
34
139
  setSandboxSize(size: SandboxSize): Promise<SandboxSize>;
35
140
  /** The caller's default sandbox size for new `@coder` sessions. */
36
141
  static defaultSandboxSize(client: MacroClient): Promise<SandboxSize>;
37
142
  /** Set the caller's default sandbox size for the next `@coder` mention. */
38
143
  static setDefaultSandboxSize(client: MacroClient, size: SandboxSize): Promise<SandboxSize>;
39
- /** Send a prompt or lifecycle operation to the live agent session. */
40
- control(action: AgentAction): Promise<AgentActionId>;
144
+ /** What the caller's new coding sessions are told to do beyond their assignment. */
145
+ static codingPreferences(client: MacroClient): Promise<CodingPreferencesBody>;
146
+ /** Replace the caller's coding preferences. */
147
+ static setCodingPreferences(client: MacroClient, preferences: CodingPreferencesBody): Promise<CodingPreferencesBody>;
148
+ /**
149
+ * Send a prompt or lifecycle operation to the live agent session.
150
+ *
151
+ * The returned `actionId` matches `requestId` on the folded message the
152
+ * action derives once it dispatches. A `queued` status means a turn was
153
+ * running: the action waits in the session's queue ({@link queue}) and
154
+ * dispatches when that turn ends.
155
+ */
156
+ control(action: AgentAction): Promise<ControlResponse>;
157
+ /**
158
+ * Send a prompt to the session — sugar over {@link control}.
159
+ *
160
+ * `attachments` are files the prompt refers to, each by a URL the agent
161
+ * can fetch (a static file service URL in practice); they reach the agent
162
+ * as ACP `resource_link` blocks after the text.
163
+ */
164
+ prompt(text: string, attachments?: PromptAttachment[]): Promise<ControlResponse>;
165
+ /**
166
+ * The actions waiting to dispatch in this session, oldest first. Each can
167
+ * be edited or removed until it dispatches.
168
+ */
169
+ queue(): Promise<QueuedAction[]>;
170
+ /** Read the latest captured GitHub pull request changes and capture status. */
171
+ changes(): Promise<AgentSessionChangesResponse>;
172
+ /** Read the unified diff of the latest captured changeset. */
173
+ changesPatch(): Promise<string>;
174
+ /** Request a fresh capture and return the current state while it runs. */
175
+ refreshChanges(): Promise<AgentSessionChangesResponse>;
41
176
  /** Read the complete raw protocol log for this session. */
42
177
  log(): Promise<AgentSessionLogResponse>;
178
+ /** Persisted reviews scoped to this session, with or without a code execution. */
179
+ readonly reviews: {
180
+ create: (input: CreateReviewOptions) => Promise<SessionReview>;
181
+ byId: (id: string) => SessionReview;
182
+ };
183
+ /** Saved code executions scoped to this session. Handle construction makes no request. */
184
+ readonly codeExecutions: {
185
+ byId: (id: string) => CodeExecution;
186
+ };
43
187
  /** Delete this session and any live resources it owns. */
44
188
  delete(): Promise<void>;
45
189
  }
@@ -0,0 +1,43 @@
1
+ import type { ExecutionRecord } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { AgentSession } from './agent-session';
5
+ import { type CreateReviewOptions, SessionReview } from './review';
6
+ /** A saved code execution belonging to one agent session. */
7
+ export declare class CodeExecution extends MacroEntity<ExecutionRecord> {
8
+ private readonly parent;
9
+ private constructor();
10
+ /** Construct a lazy execution handle within its owning session. */
11
+ static byId(client: MacroClient, session: AgentSession, id: string): CodeExecution;
12
+ protected fetch(): Promise<ExecutionRecord>;
13
+ /** Persistent UI blocks, independent of the execution lifetime. */
14
+ readonly reviews: {
15
+ create: (input: CreateReviewOptions) => Promise<SessionReview>;
16
+ list: () => Promise<SessionReview[]>;
17
+ };
18
+ /** The session this execution belongs to. */
19
+ session(): AgentSession;
20
+ /** Saved execution state. Call refresh to observe subsequent changes. */
21
+ readonly status: () => Promise<import("../../../generated/agent-harness").ExecutionStatus>;
22
+ /** The submitted JavaScript module source. */
23
+ readonly source: () => Promise<string>;
24
+ /** Legacy bridge calls; direct HTTP executions leave this empty. */
25
+ readonly calls: () => Promise<import("../../../generated/agent-harness").RecordedToolCall[]>;
26
+ /** Execution failure text, when present. */
27
+ readonly error: () => Promise<string | undefined>;
28
+ /** The program's returned JSON; preserves an explicit null result. */
29
+ result(): Promise<unknown>;
30
+ /** Reload the saved state, for example after a running execution completes. */
31
+ refresh(): Promise<this>;
32
+ }
33
+ /** JSON data returned to the model, plus references to independently saved UI. */
34
+ export type CodeResult = {
35
+ data: JsonValue;
36
+ reviews: Array<{
37
+ kind: 'email' | 'calendar';
38
+ id: string;
39
+ }>;
40
+ };
41
+ export type JsonValue = null | boolean | number | string | JsonValue[] | {
42
+ [key: string]: JsonValue;
43
+ };
@@ -0,0 +1,54 @@
1
+ import type { AgentConversationDto, AgentConversationTurnDto } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { Agent } from '../agents/agent';
4
+ import type { Channel } from '../channels/channel';
5
+ import { Message } from '../channels/message';
6
+ import { AgentSession } from './agent-session';
7
+ /** An agent's conversation in one channel. */
8
+ export declare class AgentConversation {
9
+ private readonly client;
10
+ /** Parent channel. */
11
+ readonly channel: Channel;
12
+ private readonly record;
13
+ constructor(client: MacroClient,
14
+ /** Parent channel. */
15
+ channel: Channel, record: AgentConversationDto);
16
+ /** The agent taking part. */
17
+ agent(): Agent;
18
+ /** Conversation sessions with their current flag. */
19
+ sessions(): {
20
+ session: AgentSession;
21
+ isCurrent: boolean;
22
+ createdAt: string;
23
+ }[];
24
+ /** Recorded conversation turns. */
25
+ turns(): ConversationTurn[];
26
+ /** Start a fresh conversation from one of its sessions. */
27
+ startFresh(session: AgentSession): Promise<void>;
28
+ /** Serialize scoped identity. */
29
+ toJSON(): {
30
+ channelId: string;
31
+ agentId: string;
32
+ };
33
+ }
34
+ /** One agent conversation turn, identified by its source message. */
35
+ export declare class ConversationTurn {
36
+ private readonly client;
37
+ /** Parent conversation. */
38
+ readonly conversation: AgentConversation;
39
+ private readonly record;
40
+ constructor(client: MacroClient,
41
+ /** Parent conversation. */
42
+ conversation: AgentConversation, record: AgentConversationTurnDto);
43
+ /** Originating message. */
44
+ source(): Message;
45
+ /** Session that handled this turn. */
46
+ session(): AgentSession;
47
+ /** Retry with a caller persisted action nonce. Never retries automatically. */
48
+ retry(actionId: string): Promise<void>;
49
+ /** Serialize scoped identity. */
50
+ toJSON(): {
51
+ channelId: string;
52
+ sourceMessageId: string;
53
+ };
54
+ }
@@ -1,6 +1,6 @@
1
- import type { SandboxSize } from '../../../generated/agent-harness/types.gen';
1
+ import type { CodingPreferencesBody, SandboxSize } from '../../../generated/agent-harness/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
- import { AgentSession } from './agent-session';
3
+ import { AgentSession, type CreateManagedSessionOptions, type SelectableRepository } from './agent-session';
4
4
  /** Entry point for coding-agent sessions. */
5
5
  export declare class AgentSessionNamespace {
6
6
  private readonly client;
@@ -8,11 +8,29 @@ export declare class AgentSessionNamespace {
8
8
  /** A handle to an agent session by id. Details load on first access. */
9
9
  byId(id: string): AgentSession;
10
10
  /** Create a managed agent session. */
11
- createManaged(opts?: {
12
- prompt?: string;
13
- }): Promise<AgentSession>;
11
+ createManaged(opts?: CreateManagedSessionOptions): Promise<AgentSession>;
12
+ /**
13
+ * The GitHub repositories the caller can hand a managed session, with the
14
+ * branch each one's sessions start on by default.
15
+ */
16
+ repositories(): Promise<SelectableRepository[]>;
17
+ /**
18
+ * Branch names on one repository the caller can start a managed session
19
+ * from. `repoUrl` is one of the URLs {@link AgentSessionNamespace.repositories}
20
+ * lists.
21
+ */
22
+ repositoryBranches(repoUrl: string): Promise<string[]>;
23
+ /**
24
+ * The sessions linked to the GitHub pull request at `url` that the caller
25
+ * can view.
26
+ */
27
+ forPullRequest(url: string): Promise<AgentSession[]>;
14
28
  /** The caller's default sandbox size for new `@coder` sessions. */
15
29
  defaultSandboxSize(): Promise<SandboxSize>;
16
30
  /** Set the caller's default sandbox size for the next `@coder` mention. */
17
31
  setDefaultSandboxSize(size: SandboxSize): Promise<SandboxSize>;
32
+ /** What the caller's new coding sessions are told to do beyond their assignment. */
33
+ codingPreferences(): Promise<CodingPreferencesBody>;
34
+ /** Replace the caller's coding preferences. */
35
+ setCodingPreferences(preferences: CodingPreferencesBody): Promise<CodingPreferencesBody>;
18
36
  }
@@ -0,0 +1,46 @@
1
+ import type { PromptAttachment, QueuedActionDto } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ /**
4
+ * One action waiting in an agent session's server-side queue: a prompt or a
5
+ * compact accepted while a turn was running, dispatching when that turn
6
+ * ends. Until then it can be edited (prompts only), steered, or removed; once
7
+ * it has dispatched, these actions answer 404 — there is no un-sending.
8
+ *
9
+ * List-sourced only - there is no per-action GET, only the queue snapshot -
10
+ * so this wraps whatever DTO the caller already has, the same shape
11
+ * `CrmComment` wraps a list-sourced record, rather than `MacroEntity`'s
12
+ * lazy-fetch-by-id.
13
+ */
14
+ export declare class QueuedAction {
15
+ private readonly client;
16
+ private readonly sessionId;
17
+ private dto;
18
+ private constructor();
19
+ /** Wrap a queue entry already in hand (e.g. from `AgentSession.queue()`). */
20
+ static from(client: MacroClient, sessionId: string, dto: QueuedActionDto): QueuedAction;
21
+ /**
22
+ * The id the action was accepted under. Once it dispatches, this equals
23
+ * `requestId` on the folded message the action derives.
24
+ */
25
+ get actionId(): string;
26
+ /** `prompt` or `compact`; only turn-occupying actions are ever queued. */
27
+ get kind(): string;
28
+ /** The prompt's raw text, present for prompts only. What an edit replaces. */
29
+ get prompt(): string | undefined;
30
+ /** Files the prompt refers to; empty for a compact. Kept through an edit. */
31
+ get attachments(): PromptAttachment[];
32
+ /** The user who queued it, absent when a bot acted on nobody's behalf. */
33
+ get actorUserId(): string | undefined;
34
+ /** When the action was accepted, as an RFC 3339 timestamp. */
35
+ get createdAt(): string;
36
+ /**
37
+ * Replace this queued prompt's text before it dispatches. Returns this
38
+ * handle for chaining; the edit endpoint answers 204, so `prompt` is
39
+ * applied locally rather than reread from a response body.
40
+ */
41
+ edit(prompt: string): Promise<this>;
42
+ /** Move this action to the front and interrupt the current turn to run it next. */
43
+ steer(): Promise<void>;
44
+ /** Remove this action from the queue before it dispatches. */
45
+ remove(): Promise<void>;
46
+ }
@@ -0,0 +1,107 @@
1
+ import type { ReviewRecord } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { AgentSession } from './agent-session';
5
+ import type { CodeExecution } from './code-execution';
6
+ /** A persistent review remains actionable after the code execution ends. */
7
+ export declare class SessionReview extends MacroEntity<ReviewRecord> {
8
+ private readonly parent;
9
+ private constructor();
10
+ static byId(client: MacroClient, session: AgentSession, id: string): SessionReview;
11
+ static fromRecord(client: MacroClient, session: AgentSession, record: ReviewRecord): SessionReview;
12
+ static create(client: MacroClient, execution: CodeExecution, input: CreateReviewOptions): Promise<SessionReview>;
13
+ /** Present a review in a session without requiring a code execution. */
14
+ static createForSession(client: MacroClient, session: AgentSession, input: CreateReviewOptions, execution?: CodeExecution): Promise<SessionReview>;
15
+ static list(client: MacroClient, execution: CodeExecution): Promise<SessionReview[]>;
16
+ protected fetch(): Promise<ReviewRecord>;
17
+ readonly title: () => Promise<string>;
18
+ readonly kind: () => Promise<import("../../../generated/agent-harness").ReviewKind>;
19
+ session(): AgentSession;
20
+ /** Compact reference for main()'s returned reviews array. */
21
+ reference(): Promise<{
22
+ kind: ReviewRecord['kind'];
23
+ id: string;
24
+ }>;
25
+ items(): Promise<ReviewItem[]>;
26
+ refresh(): Promise<this>;
27
+ /** Submit the saved pending drafts. Never retries a conflict or ambiguous send. */
28
+ submitAll(): Promise<void>;
29
+ dismissAll(): Promise<void>;
30
+ /** @internal Handles attach the cached revision; callers must refresh after a conflict. */
31
+ private decide;
32
+ }
33
+ /** An item handle scopes edits and decisions to its persisted review. */
34
+ export declare class ReviewItem {
35
+ private readonly snapshot;
36
+ private readonly actions;
37
+ constructor(snapshot: ReviewRecord['items'][number], actions: {
38
+ edit: (draft: unknown) => Promise<void>;
39
+ submit: () => Promise<void>;
40
+ dismiss: () => Promise<void>;
41
+ });
42
+ get id(): string;
43
+ get status(): ReviewRecord['items'][number]['status'];
44
+ get draft(): unknown;
45
+ get result(): unknown;
46
+ edit(draft: unknown): Promise<void>;
47
+ submit(): Promise<void>;
48
+ dismiss(): Promise<void>;
49
+ }
50
+ /** Markdown is rendered by the ordinary email action; the UI can edit each draft. */
51
+ export type ReviewEmailDraft = {
52
+ subject: string;
53
+ body: string;
54
+ to: Array<{
55
+ email: string;
56
+ name?: string | null;
57
+ }>;
58
+ cc?: Array<{
59
+ email: string;
60
+ name?: string | null;
61
+ }>;
62
+ bcc?: Array<{
63
+ email: string;
64
+ name?: string | null;
65
+ }>;
66
+ replyingToId?: string | null;
67
+ includeSignature?: boolean | null;
68
+ attachments?: Array<{
69
+ documentId: string;
70
+ }>;
71
+ };
72
+ export type CreateReviewOptions = {
73
+ kind: 'email';
74
+ title: string;
75
+ drafts: ReviewEmailDraft[];
76
+ } | {
77
+ kind: 'calendar';
78
+ title: string;
79
+ drafts: ReviewCalendarDraft[];
80
+ };
81
+ /** Calendar drafts use the existing calendar composer and creation action. */
82
+ export type ReviewCalendarDraft = {
83
+ title: string;
84
+ time: import('../../../generated/calendar/types.gen').EventTime;
85
+ description?: string | null;
86
+ location?: string | null;
87
+ attendees?: Array<{
88
+ email: string;
89
+ isOptional?: boolean;
90
+ }>;
91
+ calendarId?: string | null;
92
+ recurrenceLines?: string[];
93
+ addMacroCall?: boolean;
94
+ addGoogleMeet?: boolean;
95
+ reminders?: {
96
+ useDefault: boolean;
97
+ overrides?: Array<{
98
+ method: string;
99
+ minutes: number;
100
+ }>;
101
+ } | null;
102
+ eventType?: 'default' | 'out_of_office';
103
+ outOfOffice?: {
104
+ autoDeclineMode?: 'decline_none' | 'decline_all' | 'decline_new_only';
105
+ declineMessage?: string | null;
106
+ } | null;
107
+ };
@@ -0,0 +1,21 @@
1
+ import type { AnswerToolApprovalRequest } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { AgentSession } from './agent-session';
4
+ /** A permission request scoped to its originating agent session. */
5
+ export declare class ToolApproval {
6
+ private readonly client;
7
+ /** Owning session. */
8
+ readonly session: AgentSession;
9
+ /** Approval identity. */
10
+ readonly id: string;
11
+ private constructor();
12
+ /** Construct a scoped approval handle. */
13
+ static byId(client: MacroClient, session: AgentSession, id: string): ToolApproval;
14
+ /** Answer the approval using the generated discriminated answer contract. */
15
+ answer(answer: AnswerToolApprovalRequest['answer']): Promise<import("../../../generated/agent-harness").AnswerToolApprovalResponse>;
16
+ /** Serialize scoped identity only. */
17
+ toJSON(): {
18
+ id: string;
19
+ sessionId: string;
20
+ };
21
+ }