Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(agents): replace legacy chat tools with session workflows (#8303)

Eric Hayesb392a834d91c
diff --git a/.github/workflows/code_check_cloud_storage.yml b/.github/workflows/code_check_cloud_storage.yml
index 04a71023bf..0d836e99a8 100644
--- a/.github/workflows/code_check_cloud_storage.yml
+++ b/.github/workflows/code_check_cloud_storage.yml
@@ -501,6 +501,7 @@ jobs:
env:
RUST_PACKAGES: ${{ needs.path-check.outputs.rust_packages }}
NEXTEST_TEST_THREADS: '32'
+ CARGO_BUILD_JOBS: '2'
RUSTFLAGS: '-Dwarnings -C link-arg=-fuse-ld=mold'
SCCACHE_IDLE_TIMEOUT: '0'
services:
diff --git a/Cargo.lock b/Cargo.lock
index 72755d2d57..13349adcab 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -723,6 +723,7 @@ dependencies = [
"macro_db_migrator",
"macro_event_broker",
"macro_event_topics",
+ "macro_tower_layers",
"macro_user_id",
"macro_uuid",
"messages",
@@ -1030,6 +1031,7 @@ dependencies = [
"channels",
"chat",
"chrono",
+ "clap",
"cognition",
"collab_surface",
"connection",
diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md
index 198cf68fd9..d49c7e1353 100644
--- a/apps/docs/AGENTS.md
+++ b/apps/docs/AGENTS.md
@@ -16,7 +16,7 @@ expose.
- Configuration lives in `docs.json`
- Run `mint dev` to preview locally
- Run `mint broken-links` to check links
-- MCP tool reference pages under `AI/mcp/tools/` are generated by `scripts/generate-mcp-tool-pages.ts` from the Rust tool schemas in `crates/ai_tools` — fix the generator or schemas, not the output
+- MCP tool reference pages under `AI/mcp/tools/` are generated by `scripts/generate-mcp-tool-pages.ts` from the current MCP registry (`gen_tool_schemas --mcp`) in `crates/ai_tools`; historical frontend schemas must not feed public documentation — fix the generator or schemas, not the output
## Terminology
diff --git a/apps/docs/AI/mcp/tools/content-search.mdx b/apps/docs/AI/mcp/tools/content-search.mdx
index a502c82240..1b9efaa834 100644
--- a/apps/docs/AI/mcp/tools/content-search.mdx
+++ b/apps/docs/AI/mcp/tools/content-search.mdx
@@ -3,21 +3,21 @@ title: ContentSearch
description: >-
Search items by their content: document body text; email
subject/body/sender/recipient/cc/bcc and the display names on those addresses;
- chat messages; call transcripts.
+ agent session messages; call transcripts.
---
# ContentSearch
-Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; chat messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For chats, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as \{label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
+Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; agent session messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For agent sessions, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as \{label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `query` | string | Yes | The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For chats/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix. |
+| `query` | string | Yes | The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For sessions/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix. |
| `matchType` | `"partial"` \| `"exact"` | No | How search tools match query terms. Restricted to partial/exact — the backend also supports regexp and an internal query mode, but those are not offered to the model. |
-| `entityTypes` | (`"agent_sessions"` \| `"documents"` \| `"chats"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"` \| `"calendar_events"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. Projects and calendar events carry no indexed content, so they never match here — search those by name with NameSearch instead. |
+| `entityTypes` | (`"agent_sessions"` \| `"documents"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"` \| `"calendar_events"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. Projects and calendar events carry no indexed content, so they never match here — search those by name with NameSearch instead. |
| `agentSessionIds` | string[] | No | Search only the transcripts of these agent sessions, by id, and nothing else. Use it with your own session id to find the exact words of something said earlier in your conversation, including parts that were summarized to keep it within your context. Omit to search every type. |
| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results. |
-| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records) can match, so channels are dropped while a tag filter is active. |
+| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, projects, call records) can match, so channels are dropped while a tag filter is active. |
| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
diff --git a/apps/docs/AI/mcp/tools/create-agent-session.mdx b/apps/docs/AI/mcp/tools/create-agent-session.mdx
new file mode 100644
index 0000000000..4f0cd14d74
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/create-agent-session.mdx
@@ -0,0 +1,16 @@
+---
+title: CreateAgentSession
+description: >-
+ Start a new session with a coding or chat agent from ListAgents.
+---
+
+# CreateAgentSession
+
+Start a new session with a coding or chat agent from ListAgents. Provide the agent botId and a self-contained initial prompt. The new session does not inherit this conversation. Returns its session ID after the first prompt is accepted, not completed work. Use ManageAgentSession to continue an existing session. Create once; do not automatically retry after an uncertain failure.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `agentId` | string | Yes | Agent persona botId from ListAgents. |
+| `prompt` | string | Yes | Complete initial task and relevant context. |
diff --git a/apps/docs/AI/mcp/tools/create-channel-media-upload.mdx b/apps/docs/AI/mcp/tools/create-channel-media-upload.mdx
new file mode 100644
index 0000000000..546600d670
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/create-channel-media-upload.mdx
@@ -0,0 +1,17 @@
+---
+title: CreateChannelMediaUpload
+description: >-
+ Reserve a direct upload for an image or video to attach to a channel message;
+ use this for media too large to pass inline, such as screen recordings.
+---
+
+# CreateChannelMediaUpload
+
+Reserve a direct upload for an image or video to attach to a channel message; use this for media too large to pass inline, such as screen recordings. Returns an uploadUrl: immediately PUT the raw file bytes to it from your shell with the returned contentType as the Content-Type header (see uploadCommand), then call SendChannelMessage with an attachment whose id is attachmentId and whose kind is the returned kind. The URL must be used within 2 minutes; call again for a fresh one if it expires. Only images and videos are accepted; attach other files by uploading them as documents and passing the document ID.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fileName` | string | Yes | Filename including its extension, for example demo.mp4. Do not include a directory path. |
+| `contentType` | string | No | MIME type such as video/mp4 or image/png. Omit to infer it from the fileName extension. |
diff --git a/apps/docs/AI/mcp/tools/create-confirmed-calendar-event.mdx b/apps/docs/AI/mcp/tools/create-confirmed-calendar-event.mdx
deleted file mode 100644
index b4170dc8ec..0000000000
--- a/apps/docs/AI/mcp/tools/create-confirmed-calendar-event.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: CreateConfirmedCalendarEvent
-description: >-
- Create a calendar event immediately, with no review card or composer.
----
-
-# CreateConfirmedCalendarEvent
-
-Create a calendar event immediately, with no review card or composer. Only for a prompt that came from a channel or document thread (the context block says so), where there is nothing to review a draft in. The event is always shown before it is created, even when the user's request already spelled the whole thing out: in one turn write it into the thread - title, date and time with its time zone, duration, guests, location, provider conference or Macro call, recurrence - ask whether to create it, and stop there. Call this tool only in a later turn, once the user has replied approving that specific event, quoting that reply verbatim in userConfirmation. Being asked to schedule something is a request to draft the event, never approval to create it, so a userConfirmation quoting the request that asked you to set it up - rather than the reply approving the event you wrote out - is wrong. Never call it in the agent session view or in chat: use CreateCalendarEvent there, whose review card or composer is the confirmation. Takes the same fields as CreateCalendarEvent; the event is written to the calendar provider at once and any attendees receive invitations.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `title` | string | Yes | The event title. |
-| `time` | EventTimeInput | Yes | The mutually exclusive time shape supplied to calendar tools. |
-| `description` | string | No | Optional event body/description. |
-| `location` | string | No | Optional physical or virtual location label. |
-| `attendees` | AttendeeInput[] | No | Attendees to invite by email. They are notified by the calendar provider as soon as the event is created. Omit for a solo event. |
-| `recurrenceLines` | string[] | No | Raw RFC 5545 recurrence lines (RRULE, RDATE, EXDATE), e.g. ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE"]. Omit for a one-off event. |
-| `calendarId` | string | No | Calendar to create the event on, from ListCalendars. Omit to use the user's primary calendar. |
-| `reminders` | EventRemindersInput | No | Reminder configuration for the event. Omit to use the selected calendar's defaults. |
-| `addMacroCall` | boolean | No | Attach a freshly created Macro call to the event: a Macro meeting link scheduled to the event's times, written into the event's location and description. Mutually exclusive with `addConference`. |
-| `addConference` | boolean | No | Attach a conference supported by this calendar: Google Meet or Microsoft Teams. Check ListCalendars capabilities first. |
-| `eventType` | `"default"` \| `"out_of_office"` | No | The kind of event a create tool call makes. |
-| `outOfOffice` | OutOfOfficeInput | No | Out-of-office decline behavior, used only when eventType is "out_of_office". Omit to just block the time; set `autoDeclineMode` to "decline_all" or "decline_new_only" to have the calendar integration decline conflicting meetings, optionally with a `declineMessage`. |
-| `userConfirmation` | string | Yes | The user's own message approving this specific event, quoted verbatim - for example their "yes, go ahead" in reply to the event you wrote out for them. It is a reply to your draft, never the earlier request that asked you to schedule something: if the user has not yet seen this event, there is nothing to quote here and the tool must not be called. Required: do not paraphrase it, and never supply it yourself. |
diff --git a/apps/docs/AI/mcp/tools/create-project.mdx b/apps/docs/AI/mcp/tools/create-project.mdx
index 1ba5a0889e..b7bfdc6414 100644
--- a/apps/docs/AI/mcp/tools/create-project.mdx
+++ b/apps/docs/AI/mcp/tools/create-project.mdx
@@ -6,7 +6,7 @@ description: >-
# CreateProject
-Create a project — shown as a folder in the app UI. Documents, AI chats, email threads, and other projects can be placed inside it.
+Create a project — shown as a folder in the app UI. Documents, email threads, and other projects can be placed inside it.
## Parameters
diff --git a/apps/docs/AI/mcp/tools/create-tag.mdx b/apps/docs/AI/mcp/tools/create-tag.mdx
index 999e217763..715ab519f9 100644
--- a/apps/docs/AI/mcp/tools/create-tag.mdx
+++ b/apps/docs/AI/mcp/tools/create-tag.mdx
@@ -2,13 +2,12 @@
title: CreateTag
description: >-
Create a new tag — a colored label the user can apply to documents, emails,
- tasks, AI chats, and projects — in the user's personal set or their team's
- shared set.
+ tasks, and projects — in the user's personal set or their team's shared set.
---
# CreateTag
-Create a new tag — a colored label the user can apply to documents, emails, tasks, AI chats, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead.
+Create a new tag — a colored label the user can apply to documents, emails, tasks, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead.
## Parameters
diff --git a/apps/docs/AI/mcp/tools/discover-connectors.mdx b/apps/docs/AI/mcp/tools/discover-connectors.mdx
deleted file mode 100644
index 10ee45ecff..0000000000
--- a/apps/docs/AI/mcp/tools/discover-connectors.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: DiscoverConnectors
-description: >-
- Find an integration when an external app is missing or a workflow requires an
- unconnected account, including native import tools that need a connector.
----
-
-# DiscoverConnectors
-
-Find an integration when an external app is missing or a workflow requires an unconnected account, including native import tools that need a connector. Use SearchTools for available actions. Search by app name, then inspect a returned app_slug to see its actual tools and connection status. Only recommend connecting if an advertised tool supports the task; an app's name alone is not evidence. Inspection does not load or execute tools. If suitable and unconnected, include the returned connect_markup in your reply and explain what connecting enables. After connection, use SearchTools again in the same agent session to load and call the new tools.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `request` | DiscoveryRequest | Yes | Search by app name, then inspect a returned slug before recommending auth. |
diff --git a/apps/docs/AI/mcp/tools/display-results.mdx b/apps/docs/AI/mcp/tools/display-results.mdx
deleted file mode 100644
index 7189bee4ff..0000000000
--- a/apps/docs/AI/mcp/tools/display-results.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-title: DisplayResults
-description: >-
- Present results to the user as a rich view.
----
-
-# DisplayResults
-
-Present results to the user as a rich view. The `view` argument is a dynamic-UI view object (a title plus an ordered list of widgets) following the dynamic-UI schema provided to you. The view is rendered immediately in the chat; this tool returns as soon as it is dispatched.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `view` | any | Yes | The dynamic-UI view to render: an object with an optional `title` and a `widgets` array, per the provided dynamic-UI schema. |
diff --git a/apps/docs/AI/mcp/tools/duplicate-item.mdx b/apps/docs/AI/mcp/tools/duplicate-item.mdx
index f628ee09f8..f7f91fae25 100644
--- a/apps/docs/AI/mcp/tools/duplicate-item.mdx
+++ b/apps/docs/AI/mcp/tools/duplicate-item.mdx
@@ -1,18 +1,18 @@
---
title: DuplicateItem
description: >-
- Make a copy of a document (including a task) or an AI chat, owned by the user,
- as the Duplicate action in the app does.
+ Make a copy of a document (including a task), owned by the user, as the
+ Duplicate action in the app does.
---
# DuplicateItem
-Make a copy of a document (including a task) or an AI chat, owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id.
+Make a copy of a document (including a task), owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"document"` \| `"chat"` | Yes | The kind of item to duplicate. |
+| `entityType` | `"document"` | Yes | The kind of item to duplicate. |
| `entityId` | string | Yes | The id of the item to duplicate. |
-| `name` | string | No | Name for the copy of a document. Omit to use "\<original name> copy". AI chat copies always keep the original name. |
+| `name` | string | No | Name for the copy of a document. Omit to use "\<original name> copy". |
diff --git a/apps/docs/AI/mcp/tools/get-entity-properties.mdx b/apps/docs/AI/mcp/tools/get-entity-properties.mdx
index bb3f9c9892..bf0b3b5298 100644
--- a/apps/docs/AI/mcp/tools/get-entity-properties.mdx
+++ b/apps/docs/AI/mcp/tools/get-entity-properties.mdx
@@ -14,4 +14,4 @@ Get all properties attached to an entity (document, project, CRM company, etc.).
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `entity_id` | string | Yes | The ID of the entity to get properties for. |
-| `entity_type` | `"document"` \| `"initiative"` \| `"project"` \| `"chat"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. Tasks are targeted as `document`; email threads (type `email` in ListEntities and search results) are targeted as `thread`. |
+| `entity_type` | `"document"` \| `"initiative"` \| `"project"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. Tasks are targeted as `document`; email threads (type `email` in ListEntities and search results) are targeted as `thread`. |
diff --git a/apps/docs/AI/mcp/tools/index.mdx b/apps/docs/AI/mcp/tools/index.mdx
index 88909089ee..f394844a92 100644
--- a/apps/docs/AI/mcp/tools/index.mdx
+++ b/apps/docs/AI/mcp/tools/index.mdx
@@ -18,12 +18,13 @@ These pages are generated from Macro's Rust MCP tool registry.
- [ConfigureAgent](/AI/mcp/tools/configure-agent)
- [ConfigureBot](/AI/mcp/tools/configure-bot)
- [ContentSearch](/AI/mcp/tools/content-search)
+- [CreateAgentSession](/AI/mcp/tools/create-agent-session)
- [CreateBookingLink](/AI/mcp/tools/create-booking-link)
- [CreateBot](/AI/mcp/tools/create-bot)
- [CreateCalendarEvent](/AI/mcp/tools/create-calendar-event)
- [CreateChannel](/AI/mcp/tools/create-channel)
+- [CreateChannelMediaUpload](/AI/mcp/tools/create-channel-media-upload)
- [CreateCompany](/AI/mcp/tools/create-company)
-- [CreateConfirmedCalendarEvent](/AI/mcp/tools/create-confirmed-calendar-event)
- [CreateContact](/AI/mcp/tools/create-contact)
- [CreateDocument](/AI/mcp/tools/create-document)
- [CreateForm](/AI/mcp/tools/create-form)
@@ -46,9 +47,7 @@ These pages are generated from Macro's Rust MCP tool registry.
- [DeleteRoutine](/AI/mcp/tools/delete-routine)
- [DeleteTag](/AI/mcp/tools/delete-tag)
- [DescribeDatabase](/AI/mcp/tools/describe-database)
-- [DiscoverConnectors](/AI/mcp/tools/discover-connectors)
- [DispatchCodingAgent](/AI/mcp/tools/dispatch-coding-agent)
-- [DisplayResults](/AI/mcp/tools/display-results)
- [DuplicateItem](/AI/mcp/tools/duplicate-item)
- [EditBookingLink](/AI/mcp/tools/edit-booking-link)
- [EditChannelMessage](/AI/mcp/tools/edit-channel-message)
@@ -96,7 +95,7 @@ These pages are generated from Macro's Rust MCP tool registry.
- [ListSkills](/AI/mcp/tools/list-skills)
- [ListTags](/AI/mcp/tools/list-tags)
- [ListTeamMembers](/AI/mcp/tools/list-team-members)
-- [LoadTools](/AI/mcp/tools/load-tools)
+- [ManageAgentSession](/AI/mcp/tools/manage-agent-session)
- [ManageBotChannelAccess](/AI/mcp/tools/manage-bot-channel-access)
- [ManageChannelParticipants](/AI/mcp/tools/manage-channel-participants)
- [MarkNotificationsDone](/AI/mcp/tools/mark-notifications-done)
@@ -109,12 +108,13 @@ These pages are generated from Macro's Rust MCP tool registry.
- [QueryDatabase](/AI/mcp/tools/query-database)
- [ReactToChannelMessage](/AI/mcp/tools/react-to-channel-message)
- [ReadActivity](/AI/mcp/tools/read-activity)
+- [ReadAgentSession](/AI/mcp/tools/read-agent-session)
+- [ReadAgentSessionSharing](/AI/mcp/tools/read-agent-session-sharing)
- [ReadBookingSettings](/AI/mcp/tools/read-booking-settings)
- [ReadCallRecord](/AI/mcp/tools/read-call-record)
- [ReadChannelMessageContext](/AI/mcp/tools/read-channel-message-context)
- [ReadChannelMessages](/AI/mcp/tools/read-channel-messages)
- [ReadChannelThread](/AI/mcp/tools/read-channel-thread)
-- [ReadChat](/AI/mcp/tools/read-chat)
- [ReadContent](/AI/mcp/tools/read-content)
- [ReadDesign](/AI/mcp/tools/read-design)
- [ReadForm](/AI/mcp/tools/read-form)
@@ -128,7 +128,6 @@ These pages are generated from Macro's Rust MCP tool registry.
- [ReadRoutine](/AI/mcp/tools/read-routine)
- [ReadSkill](/AI/mcp/tools/read-skill)
- [ReadSpreadsheet](/AI/mcp/tools/read-spreadsheet)
-- [ReadThread](/AI/mcp/tools/read-thread)
- [ReadWordDocument](/AI/mcp/tools/read-word-document)
- [RemoveFromPipeline](/AI/mcp/tools/remove-from-pipeline)
- [RenameChannel](/AI/mcp/tools/rename-channel)
@@ -139,11 +138,8 @@ These pages are generated from Macro's Rust MCP tool registry.
- [SaveDatabaseQuery](/AI/mcp/tools/save-database-query)
- [SaveDatabaseView](/AI/mcp/tools/save-database-view)
- [SearchSkills](/AI/mcp/tools/search-skills)
-- [SearchTools](/AI/mcp/tools/search-tools)
- [SelfKnowledge](/AI/mcp/tools/self-knowledge)
- [SendChannelMessage](/AI/mcp/tools/send-channel-message)
-- [SendConfirmedEmail](/AI/mcp/tools/send-confirmed-email)
-- [SendEmail](/AI/mcp/tools/send-email)
- [SetEntityProperty](/AI/mcp/tools/set-entity-property)
- [SetFavorite](/AI/mcp/tools/set-favorite)
- [SetFormAccess](/AI/mcp/tools/set-form-access)
@@ -151,6 +147,7 @@ These pages are generated from Macro's Rust MCP tool registry.
- [ShareWithChannel](/AI/mcp/tools/share-with-channel)
- [Subagent](/AI/mcp/tools/subagent)
- [TextEditorCodeExecution](/AI/mcp/tools/text-editor-code-execution)
+- [UpdateAgentSessionSharing](/AI/mcp/tools/update-agent-session-sharing)
- [UpdateBookingSettings](/AI/mcp/tools/update-booking-settings)
- [UpdateCalendarEvent](/AI/mcp/tools/update-calendar-event)
- [UpdateCallRecord](/AI/mcp/tools/update-call-record)
diff --git a/apps/docs/AI/mcp/tools/list-entities.mdx b/apps/docs/AI/mcp/tools/list-entities.mdx
index 4530cd91db..785c4c7e78 100644
--- a/apps/docs/AI/mcp/tools/list-entities.mdx
+++ b/apps/docs/AI/mcp/tools/list-entities.mdx
@@ -6,18 +6,18 @@ description: >-
# ListEntities
-Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as "what happened today", "what's going on", "catch me up", or "what happened in standup today"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as "list my tasks", "tasks assigned to me", or "tasks I completed yesterday", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype \{"l":\{"dst":"task"}} and includeTypes ["document"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|\<their email address from context>. For "completed yesterday", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as \{label, scope} pairs. To filter by tag (e.g. "my items tagged bug-report"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
+Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, agent sessions, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as "what happened today", "what's going on", "catch me up", or "what happened in standup today"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as "list my tasks", "tasks assigned to me", or "tasks I completed yesterday", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype \{"l":\{"dst":"task"}} and includeTypes ["document"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|\<their email address from context>. For "completed yesterday", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, projects, emails, and call records include the tags visible to the user as \{label, scope} pairs. To filter by tag (e.g. "my items tagged bug-report"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `includeTypes` | (`"calendar_event"` \| `"document"` \| `"ai_chat"` \| `"project"` \| `"email"` \| `"channel"` \| `"channel_thread"` \| `"call"` \| `"foreign_entity"`)[] | No | Filter returned items to specific item types. If not provided, returns all types. Example: ["document", "email"] returns only documents and emails. Macro tasks are returned as document items, so use includeTypes=["document"] with df subtype task for task requests. This is folded into the AST and applied as part of cursor-level filtering. |
+| `includeTypes` | (`"calendar_event"` \| `"document"` \| `"agent_session"` \| `"project"` \| `"email"` \| `"channel"` \| `"channel_thread"` \| `"call"` \| `"foreign_entity"`)[] | No | Filter returned items to specific item types. If not provided, returns all types. Example: ["document", "email"] returns only documents and emails. Macro tasks are returned as document items, so use includeTypes=["document"] with df subtype task for task requests. This is folded into the AST and applied as part of cursor-level filtering. |
| `favoritesOnly` | boolean | No | Only return items the user has favorited (starred). Use for requests like "my favorites" or "what have I starred". Combine with includeTypes and the other filters as usual. Favorite or unfavorite an item with SetFavorite. |
| `sortBy` | `"recently_viewed"` \| `"recently_updated"` \| `"recently_created"` | No | Sort order for the list entities AI tool. |
| `df` | any | No | Full soup AST document filter (df). Use the same shape as /items/soup/ast, e.g. \{"l":\{"id":"..."}}. For Macro tasks, use \{"l":\{"dst":"task"}}; for skills, \{"l":\{"dst":"skill"}}. For "completed yesterday", AND the task subtype with updatedAt bounds, e.g. \{"&":[\{"l":\{"dst":"task"}},\{"&":[\{"l":\{"ua":\{"gte":"\<start>"}}},\{"l":\{"ua":\{"lt":"\<end>"}}}]}]} using ISO timestamps. |
| `pf` | any | No | Full soup AST project filter (pf). |
-| `cf` | any | No | Full soup AST AI chat filter (cf). |
+| `asf` | any | No | Agent-session filter (asf): use \{"l":\{"id":"\<session UUID>"}} for a session, or \{"l":\{"o":"macro\|[email protected]"}} for an owner. |
| `emailPreset` | `"signal"` | No | High-level email filter preset. Use "signal" for signal emails. Signal emails and important emails are synonymous: if the user asks for important emails, use emailPreset="signal". This expands to the email AST \{"&":[\{"l":\{"Importance":true}},\{"l":\{"Shared":"exclude"}}]} and defaults results to emails if includeTypes is omitted. |
| `ef` | any | No | Advanced full soup AST email filter (ef). Prefer emailPreset="signal" for common requests. Signal emails and important emails are synonymous; they use \{"&":[\{"l":\{"Importance":true}},\{"l":\{"Shared":"exclude"}}]}. Supports filtering by thread timestamp: \{"l":\{"ca":\{"gte":"\<start>"}}} matches created_at, \{"l":\{"ua":\{"gte":"\<start>","lt":"\<end>"}}} matches updated_at, using ISO timestamps with gt/lt/gte/lte comparators. For "emails from the last 7 days", AND a ua (or ca) gte bound set to 7 days before now, e.g. \{"l":\{"ua":\{"gte":"\<7-days-ago-ISO>"}}}. |
| `chanf` | any | No | Full soup AST channel filter (chanf). |
@@ -27,6 +27,6 @@ Browse the user's Macro workspace to see recent items they have access to. Retur
| `propf` | any | No | Full soup AST property filter (propf). Use this for Macro task Status, Assignees, Priority, and other entity properties. For task Status Completed: \{"l":\{"pd":"00000001-0000-0000-0000-000000000002","et":"TASK","v":\{"so":"00000001-0000-0000-0002-000000000004"}}}. For tasks assigned to the current user: \{"l":\{"pd":"00000001-0000-0000-0000-000000000001","et":"TASK","v":\{"er":"macro\|[email protected]"}}}. Combine both with &: \{"&":[statusCompleted, assignedToMe]}. Prefer this over Linear tools for unqualified task requests. |
| `emailView` | string | No | Which mailbox view to hydrate previews from for email results. Valid values: inbox (default), sent, drafts, starred, all, important, other, or user:\<label>. When the user asks about signal or important emails, use emailView="inbox" together with emailPreset="signal" — do not set emailView="important" in that case. Only override the default when the user explicitly asks for a specific mailbox or label view (e.g. "sent", "drafts", "my Foo label"). |
| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address. Omit to span every inbox the user can access (their own plus any delegated to them). Only set this when the user scopes the request to a specific mailbox (e.g. "my work inbox", "the shared inbox"); call ListInboxes first to get the exact address. Only affects email results. |
-| `tags` | TagFilter[] | No | Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, AI chats, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags. |
+| `tags` | TagFilter[] | No | Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags. |
| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
| `limit` | integer | No | Maximum number of items to return. Defaults to 50; max 500. |
diff --git a/apps/docs/AI/mcp/tools/list-notifications.mdx b/apps/docs/AI/mcp/tools/list-notifications.mdx
index f3d21864d5..a3ce6c4f6d 100644
--- a/apps/docs/AI/mcp/tools/list-notifications.mdx
+++ b/apps/docs/AI/mcp/tools/list-notifications.mdx
@@ -14,5 +14,5 @@ List the current user's notifications. By default returns active notifications (
| --- | --- | --- | --- |
| `limit` | integer | No | Maximum number of notifications to return. Defaults to 20, max 50. |
| `states` | (`"unseen"` \| `"seen"` \| `"done"`)[] | No | Exact states to include: unseen, seen, done. Defaults to [unseen, seen]. An empty list includes all states. |
-| `includeTypes` | (`"email"` \| `"message"` \| `"channel"` \| `"document"` \| `"project"` \| `"chat"` \| `"call"` \| `"task"` \| `"github"` \| `"reminder"` \| `"calendar"` \| `"agent"`)[] | No | Filter to specific notification item types. If omitted, returns all types. Example: ["email", "message"] returns only email and message notifications. |
+| `includeTypes` | (`"email"` \| `"message"` \| `"channel"` \| `"document"` \| `"project"` \| `"call"` \| `"task"` \| `"github"` \| `"reminder"` \| `"calendar"` \| `"agent"`)[] | No | Filter to specific notification item types. If omitted, returns all types. Example: ["email", "message"] returns only email and message notifications. |
| `entities` | NotificationEntityFilter[] | No | Filter to notifications for specific entities. Pair each id with its canonical entityType to avoid ambiguity. Example: [\{"entityType":"email_thread","id":"..."}] returns notifications for one email thread. |
diff --git a/apps/docs/AI/mcp/tools/load-tools.mdx b/apps/docs/AI/mcp/tools/load-tools.mdx
deleted file mode 100644
index 666fa9dfb2..0000000000
--- a/apps/docs/AI/mcp/tools/load-tools.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: LoadTools
-description: >-
- Load tools by name (from the More Macro Tools list in your instructions, or
- from `SearchTools` results) so you can call them.
----
-
-# LoadTools
-
-Load tools by name (from the More Macro Tools list in your instructions, or from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `names` | string[] | Yes | Exact tool names to load. |
diff --git a/apps/docs/AI/mcp/tools/manage-agent-session.mdx b/apps/docs/AI/mcp/tools/manage-agent-session.mdx
new file mode 100644
index 0000000000..89302fcd58
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/manage-agent-session.mdx
@@ -0,0 +1,16 @@
+---
+title: ManageAgentSession
+description: >-
+ Rename, archive/unarchive, delete, prompt, or stop an agent session.
+---
+
+# ManageAgentSession
+
+Rename, archive/unarchive, delete, prompt, or stop an agent session. Use ListEntities or NameSearch to find sessions and ReadAgentSession to inspect them. Rename, archive, and delete require ownership; prompting and stopping require edit access. Delete releases the runtime and permanently removes the session; use only when the user asks to delete it. Prompt returns sent/queued acceptance, not completed work. After an uncertain error, read the session before retrying; never automatically resend a prompt. This tool cannot answer permission or approval requests.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sessionId` | string | Yes | Session UUID from a mention, listing, or search result. |
+| `action` | SessionAction | Yes | Session lifecycle actions available to agents. Human approvals are deliberately absent. |
diff --git a/apps/docs/AI/mcp/tools/move-to-project.mdx b/apps/docs/AI/mcp/tools/move-to-project.mdx
index 344e7f4719..8b13427dd4 100644
--- a/apps/docs/AI/mcp/tools/move-to-project.mdx
+++ b/apps/docs/AI/mcp/tools/move-to-project.mdx
@@ -1,19 +1,18 @@
---
title: MoveToProject
description: >-
- Move a document, AI chat, email thread, or project into another project
- (projects are shown as folders in the app UI), or move it out to the top
- level.
+ Move a document, email thread, or project into another project (projects are
+ shown as folders in the app UI), or move it out to the top level.
---
# MoveToProject
-Move a document, AI chat, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving an AI chat or a project requires owning it.
+Move a document, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving a project requires owning it.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"document"` \| `"chat"` \| `"email"` \| `"project"` | Yes | The kind of entity to move. |
+| `entityType` | `"document"` \| `"email"` \| `"project"` | Yes | The kind of entity to move. |
| `entityId` | string | Yes | The id of the entity to move. |
| `projectId` | string | No | The id of the destination project. Omit to move the entity out of its current project to the top level. |
diff --git a/apps/docs/AI/mcp/tools/move-to-trash.mdx b/apps/docs/AI/mcp/tools/move-to-trash.mdx
index 01f4038783..e1f853a304 100644
--- a/apps/docs/AI/mcp/tools/move-to-trash.mdx
+++ b/apps/docs/AI/mcp/tools/move-to-trash.mdx
@@ -1,17 +1,17 @@
---
title: MoveToTrash
description: >-
- Delete a document (including a task), an AI chat, or a project (folder) by
- moving it to the trash, as the Delete action in the app does.
+ Delete a document (including a task), or a project (folder) by moving it to
+ the trash, as the Delete action in the app does.
---
# MoveToTrash
-Delete a document (including a task), an AI chat, or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool.
+Delete a document (including a task), or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"document"` \| `"chat"` \| `"project"` | Yes | The kind of item to move to the trash. |
+| `entityType` | `"document"` \| `"project"` | Yes | The kind of item to move to the trash. |
| `entityId` | string | Yes | The id of the item to move to the trash. |
diff --git a/apps/docs/AI/mcp/tools/mute-notifications.mdx b/apps/docs/AI/mcp/tools/mute-notifications.mdx
index 15d7c4bcde..54161bea6d 100644
--- a/apps/docs/AI/mcp/tools/mute-notifications.mdx
+++ b/apps/docs/AI/mcp/tools/mute-notifications.mdx
@@ -13,7 +13,7 @@ Mute, snooze, or unmute notifications about one item for the user only, as Mute
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"user"` \| `"chat"` \| `"channel"` \| `"channel_message"` \| `"document"` \| `"project"` \| `"email_thread"` \| `"calendar_event"` \| `"team"` \| `"call"` \| `"foreign_entity"` \| `"static_file"` \| `"crm_company"` \| `"crm_contact"` \| `"reminder"` \| `"skill"` \| `"scheduled_action"` | Yes | Canonical entity types accepted by the notification-listing tool. This mirrors [`EntityType`] because the shared model intentionally does not depend on `schemars`, while AI tool inputs require [`JsonSchema`]. |
+| `entityType` | `"agent_session"` \| `"user"` \| `"channel"` \| `"channel_message"` \| `"document"` \| `"project"` \| `"email_thread"` \| `"calendar_event"` \| `"team"` \| `"call"` \| `"foreign_entity"` \| `"static_file"` \| `"crm_company"` \| `"crm_contact"` \| `"reminder"` \| `"skill"` \| `"scheduled_action"` | Yes | Canonical entity types accepted by the notification-listing tool. This mirrors [`EntityType`] because the shared model intentionally does not depend on `schemars`, while AI tool inputs require [`JsonSchema`]. |
| `entityId` | string | Yes | The item's id. |
| `action` | `"mute"` \| `"snooze"` \| `"unmute"` | Yes | What to do with an item's notifications. |
| `snoozeUntil` | string | No | When notifications resume, as an ISO 8601 timestamp in the future. Required for snooze; omit otherwise. |
diff --git a/apps/docs/AI/mcp/tools/name-search.mdx b/apps/docs/AI/mcp/tools/name-search.mdx
index 811806f777..27ab5c5379 100644
--- a/apps/docs/AI/mcp/tools/name-search.mdx
+++ b/apps/docs/AI/mcp/tools/name-search.mdx
@@ -1,13 +1,13 @@
---
title: NameSearch
description: >-
- Search items by their name or title: document name, email subject, chat title,
- channel name, project name, or call-record name.
+ Search items by their name or title: document name, email subject, agent
+ session title, channel name, project name, or call-record name.
---
# NameSearch
-Search items by their name or title: document name, email subject, chat title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as \{label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
+Search items by their name or title: document name, email subject, agent session title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as \{label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
## Parameters
@@ -15,7 +15,7 @@ Search items by their name or title: document name, email subject, chat title, c
| --- | --- | --- | --- |
| `name` | string | Yes | The name or title to search. Pass 1-3 keywords drawn from words that would literally appear in the title, not the user's natural-language description. Whitespace-separated terms are ANDed. For non-email types the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. For emails each term is matched against the subject. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token matching instead of prefix. |
| `matchType` | `"partial"` \| `"exact"` | No | How search tools match query terms. Restricted to partial/exact — the backend also supports regexp and an internal query mode, but those are not offered to the model. |
-| `entityTypes` | (`"agent_sessions"` \| `"documents"` \| `"chats"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"` \| `"calendar_events"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. |
+| `entityTypes` | (`"agent_sessions"` \| `"documents"` \| `"emails"` \| `"channels"` \| `"projects"` \| `"call_records"` \| `"calendar_events"`)[] | No | Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. |
| `inbox` | string | No | Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results. |
-| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records, calendar events) can match, so channels are dropped while a tag filter is active. |
+| `tags` | TagFilter[] | No | Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, projects, call records, calendar events) can match, so channels are dropped while a tag filter is active. |
| `tagsMatch` | `"any"` \| `"all"` | No | How multiple tag filters combine when filtering items. |
diff --git a/apps/docs/AI/mcp/tools/read-agent-session-sharing.mdx b/apps/docs/AI/mcp/tools/read-agent-session-sharing.mdx
new file mode 100644
index 0000000000..7e74f504b9
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-agent-session-sharing.mdx
@@ -0,0 +1,16 @@
+---
+title: ReadAgentSessionSharing
+description: >-
+ Read an agent session's current owner, link sharing, team access, and channel
+ grants.
+---
+
+# ReadAgentSessionSharing
+
+Read an agent session's current owner, link sharing, team access, and channel grants. Requires view access. Use UpdateAgentSessionSharing to change grants as the owner.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sessionId` | string | Yes | Session UUID. |
diff --git a/apps/docs/AI/mcp/tools/read-agent-session.mdx b/apps/docs/AI/mcp/tools/read-agent-session.mdx
new file mode 100644
index 0000000000..235df311ed
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/read-agent-session.mdx
@@ -0,0 +1,17 @@
+---
+title: ReadAgentSession
+description: >-
+ Read an agent session by its ID from an agent-session mention or search
+ result.
+---
+
+# ReadAgentSession
+
+Read an agent session by its ID from an agent-session mention or search result. Returns the latest 20 messages in chronological order, including prompts, replies, tool activity and errors. Optionally select a turn number to inspect earlier history. Each message is capped at 4000 characters; truncated flags identify omitted history or text. Requires view access to the session.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sessionId` | string | Yes | The agent session UUID from its mention or search result. |
+| `turn` | integer | No | Read only this turn number, as returned in messages; omit for recent history. |
diff --git a/apps/docs/AI/mcp/tools/read-chat.mdx b/apps/docs/AI/mcp/tools/read-chat.mdx
deleted file mode 100644
index c4b7d44795..0000000000
--- a/apps/docs/AI/mcp/tools/read-chat.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-title: ReadChat
-description: >-
- Retrieve a chat thread's message history by its ID.
----
-
-# ReadChat
-
-Retrieve a chat thread's message history by its ID. Returns the conversation title and messages with their roles, content, and attachment references.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `chatId` | string | Yes | The id of the chat thread to read. |
diff --git a/apps/docs/AI/mcp/tools/read-project.mdx b/apps/docs/AI/mcp/tools/read-project.mdx
index 7c5c03adae..d99287d2f9 100644
--- a/apps/docs/AI/mcp/tools/read-project.mdx
+++ b/apps/docs/AI/mcp/tools/read-project.mdx
@@ -2,12 +2,12 @@
title: ReadProject
description: >-
List the direct contents of a project (shown as a folder in the app UI): its
- documents, AI chats, and nested projects.
+ documents and nested projects.
---
# ReadProject
-List the direct contents of a project (shown as a folder in the app UI): its documents, AI chats, and nested projects. Requires view access to the project. Email threads filed into the project are not included.
+List the direct contents of a project (shown as a folder in the app UI): its documents and nested projects. Requires view access to the project. Email threads filed into the project are not included.
## Parameters
diff --git a/apps/docs/AI/mcp/tools/read-thread.mdx b/apps/docs/AI/mcp/tools/read-thread.mdx
deleted file mode 100644
index 385db634a7..0000000000
--- a/apps/docs/AI/mcp/tools/read-thread.mdx
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: ReadThread
-description: >-
- Read threaded content by ID(s).
----
-
-# ReadThread
-
-Read threaded content by ID(s). Supports reading channels, chats, and projects by their respective IDs. Use this tool when you need to retrieve the full content of a specific item(s). For documents, use ReadContent or ReadMetadata instead.
- Channel transcripts only include the latest 150 messages. Use 'messages_since' to see messages in a different time window.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `contentType` | `"channel"` \| `"channel-message"` \| `"chat-thread"` \| `"chat-message"` \| `"project"` | Yes | |
-| `ids` | string[] | Yes | ID(s) of the content to read. IMPORTANT: channel-message, chat-message, and content types support MULTIPLE ids! For all other content types (channel, chat-thread) provide a single id. |
-| `messagesSince` | string | No | A local datetime of the earliest message to include in a channel transcript following ISO 8601 format, only applicable to channels |
diff --git a/apps/docs/AI/mcp/tools/rename-item.mdx b/apps/docs/AI/mcp/tools/rename-item.mdx
index ca00397acf..9bc1070116 100644
--- a/apps/docs/AI/mcp/tools/rename-item.mdx
+++ b/apps/docs/AI/mcp/tools/rename-item.mdx
@@ -1,17 +1,17 @@
---
title: RenameItem
description: >-
- Rename a project (shown as a folder in the app) or an AI chat.
+ Rename a project (shown as a folder in the app).
---
# RenameItem
-Rename a project (shown as a folder in the app) or an AI chat. Renaming a project requires edit access; renaming an AI chat requires owning it. Use RenameDocument for documents and tasks, and RenameChannel for channels.
+Rename a project (shown as a folder in the app). Renaming a project requires edit access. Use RenameDocument for documents and tasks, and RenameChannel for channels.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"project"` \| `"chat"` | Yes | The kind of item to rename. |
+| `entityType` | `"project"` | Yes | The kind of item to rename. |
| `entityId` | string | Yes | The id of the item to rename. |
| `name` | string | Yes | The new name. |
diff --git a/apps/docs/AI/mcp/tools/search-tools.mdx b/apps/docs/AI/mcp/tools/search-tools.mdx
deleted file mode 100644
index 555228d4a9..0000000000
--- a/apps/docs/AI/mcp/tools/search-tools.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: SearchTools
-description: >-
- Find tools by keyword: Macro tools whose parameters are not loaded yet, and
- tools from connected integrations (e.g.
----
-
-# SearchTools
-
-Find tools by keyword: Macro tools whose parameters are not loaded yet, and tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub). The top matches are loaded automatically: call them by exact name on your next step. Matches past the auto-load cap come back under `additional_matches` and need `LoadTools` first. Searching is cheap, so cast a wide net.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `query` | string | Yes | Keywords describing the capability you need, e.g. "linear issue" or "github list commits". |
diff --git a/apps/docs/AI/mcp/tools/send-confirmed-email.mdx b/apps/docs/AI/mcp/tools/send-confirmed-email.mdx
deleted file mode 100644
index c2c6db4e77..0000000000
--- a/apps/docs/AI/mcp/tools/send-confirmed-email.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: SendConfirmedEmail
-description: >-
- Send an email immediately, with no review card or composer.
----
-
-# SendConfirmedEmail
-
-Send an email immediately, with no review card or composer. Only for a prompt that came from a channel or document thread (the context block says so), where there is nothing to review a draft in. The email is always shown before it is sent, even when the user's request already spelled the whole thing out: in one turn write it into the thread - recipients, subject, body - ask whether to send it, and stop there. Call this tool only in a later turn, once the user has replied approving that specific email, quoting that reply verbatim in userConfirmation. Being asked to send an email is a request to draft one, never approval to send it, so a userConfirmation quoting the request that asked you to write the email - rather than the reply approving the one you wrote - is wrong. Never call it in the agent session view or in chat: use SendEmail there, whose review card or composer is the confirmation. Takes the same fields as SendEmail; write the body in Markdown, which is rendered to HTML on send.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `subject` | string | Yes | The subject line of the email. |
-| `from` | string | No | The address of the inbox to send from, when the user has more than one connected and this email belongs to a particular one. Use the exact `emailAddress` of a connected inbox — `ListInboxes` lists them, and `GetThread` reports the `inbox` a thread belongs to. Omit it unless you know which inbox is right: a reply then goes out from the inbox that received the message it answers, and a new email from the user's primary inbox. The user can change it in the composer either way. |
-| `body` | string | Yes | The body of the email, written as Markdown. A host with a composer (chat) replaces this with the base64url-encoded HTML the composer exported before the tool runs; a host without one (an agent session) leaves the Markdown, and this tool renders it the same way. |
-| `to` | EmailRecipient[] | Yes | The primary recipients (To field). |
-| `cc` | EmailRecipient[] | No | Carbon copy recipients (optional). |
-| `bcc` | EmailRecipient[] | No | Blind carbon copy recipients (optional). |
-| `replyingToId` | string | No | The ID of a message to reply to (optional). When set, the email is sent as a reply within the same thread. |
-| `includeSignature` | boolean | No | Per-message signature override, set by the composer's signature preview — not normally by you. Omit to use the inbox's default policy (always on a new email; on replies/forwards only when the user enabled it). `false` excludes the signature for this one email. |
-| `attachments` | EmailAttachment[] | No | Macro documents to attach as files (optional). Each must be an uploaded file the user can view; together they may total 18 MB. |
-| `userConfirmation` | string | Yes | The user's own message approving this specific email, quoted verbatim - for example their "yes, send it" in reply to the email you wrote out for them. It is a reply to your draft, never the earlier request that asked you to write one: if the user has not yet seen this email, there is nothing to quote here and the tool must not be called. Required: do not paraphrase it, and never supply it yourself. |
diff --git a/apps/docs/AI/mcp/tools/send-email.mdx b/apps/docs/AI/mcp/tools/send-email.mdx
deleted file mode 100644
index b877c51ff2..0000000000
--- a/apps/docs/AI/mcp/tools/send-email.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: SendEmail
-description: >-
- Draft, compose, and send an email the user confirms in a review card or
- composer.
----
-
-# SendEmail
-
-Draft, compose, and send an email the user confirms in a review card or composer. Use this tool whenever the user asks you to draft, write, compose, or send an email (or reply to one) from the agent session view or from chat — never write the email as plain text there. It opens the draft for the user to review, edit, and confirm before it is sent, so it is the correct tool even when the user only wants a draft. Do NOT use it for a prompt that came from a channel or document thread — the context block names a conversation parent when it did, and there is no surface to review a draft in: write the email out in your reply, ask whether to send it, and use SendConfirmedEmail once the user approves. To reply to an existing message, provide the replying_to_id; the reply then goes out from the inbox that received it unless `from` says otherwise. To attach files, list the Macro documents in attachments — uploaded files such as PDFs, images, spreadsheets, or Word documents the user can view; the user can add or remove attachments in the composer before sending. Write the body in Markdown — use **bold**, *italics*, lists, links, and other standard Markdown formatting. The draft composer renders the Markdown for the user to review and edit; the composer produces HTML that is sent as the actual email body.
-
-## Parameters
-
-| Parameter | Type | Required | Description |
-| --- | --- | --- | --- |
-| `subject` | string | Yes | The subject line of the email. |
-| `from` | string | No | The address of the inbox to send from, when the user has more than one connected and this email belongs to a particular one. Use the exact `emailAddress` of a connected inbox — `ListInboxes` lists them, and `GetThread` reports the `inbox` a thread belongs to. Omit it unless you know which inbox is right: a reply then goes out from the inbox that received the message it answers, and a new email from the user's primary inbox. The user can change it in the composer either way. |
-| `body` | string | Yes | The body of the email, written as Markdown. A host with a composer (chat) replaces this with the base64url-encoded HTML the composer exported before the tool runs; a host without one (an agent session) leaves the Markdown, and this tool renders it the same way. |
-| `to` | EmailRecipient[] | Yes | The primary recipients (To field). |
-| `cc` | EmailRecipient[] | No | Carbon copy recipients (optional). |
-| `bcc` | EmailRecipient[] | No | Blind carbon copy recipients (optional). |
-| `replyingToId` | string | No | The ID of a message to reply to (optional). When set, the email is sent as a reply within the same thread. |
-| `includeSignature` | boolean | No | Per-message signature override, set by the composer's signature preview — not normally by you. Omit to use the inbox's default policy (always on a new email; on replies/forwards only when the user enabled it). `false` excludes the signature for this one email. |
-| `attachments` | EmailAttachment[] | No | Macro documents to attach as files (optional). Each must be an uploaded file the user can view; together they may total 18 MB. |
diff --git a/apps/docs/AI/mcp/tools/set-entity-property.mdx b/apps/docs/AI/mcp/tools/set-entity-property.mdx
index ea08274d13..fb3c8687ca 100644
--- a/apps/docs/AI/mcp/tools/set-entity-property.mdx
+++ b/apps/docs/AI/mcp/tools/set-entity-property.mdx
@@ -39,7 +39,7 @@ For non-system or custom properties, call GetEntityProperties first to discover
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `entity_id` | string | Yes | The ID of the entity to update. |
-| `entity_type` | `"document"` \| `"initiative"` \| `"project"` \| `"chat"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. Tasks are targeted as `document`; email threads (type `email` in ListEntities and search results) are targeted as `thread`. |
+| `entity_type` | `"document"` \| `"initiative"` \| `"project"` \| `"thread"` \| `"channel"` \| `"call"` \| `"user"` \| `"company"` | Yes | Canonical entity type accepted when an AI tool targets an entity's properties. Tasks are targeted as `document`; email threads (type `email` in ListEntities and search results) are targeted as `thread`. |
| `property_definition_id` | string | Yes | The property definition ID. Get this from GetEntityProperties results. |
| `boolean_value` | boolean | No | For boolean properties. |
| `date_value` | string | No | For date properties (ISO 8601 date-time). |
diff --git a/apps/docs/AI/mcp/tools/set-favorite.mdx b/apps/docs/AI/mcp/tools/set-favorite.mdx
index d89bff9526..b3b4de19c0 100644
--- a/apps/docs/AI/mcp/tools/set-favorite.mdx
+++ b/apps/docs/AI/mcp/tools/set-favorite.mdx
@@ -13,6 +13,6 @@ Add an item to the user's favorites (shown starred in the app sidebar) or remove
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"document"` \| `"project"` \| `"chat"` \| `"channel"` \| `"email"` \| `"call"` \| `"crm_company"` \| `"crm_contact"` | Yes | The kinds of item a user can favorite. |
+| `entityType` | `"document"` \| `"project"` \| `"channel"` \| `"email"` \| `"call"` \| `"crm_company"` \| `"crm_contact"` | Yes | The kinds of item a user can favorite. |
| `entityId` | string | Yes | The id of the item. |
| `favorite` | boolean | Yes | True to add the item to favorites, false to remove it. |
diff --git a/apps/docs/AI/mcp/tools/share-with-channel.mdx b/apps/docs/AI/mcp/tools/share-with-channel.mdx
index 12a3618c44..ff0264c63a 100644
--- a/apps/docs/AI/mcp/tools/share-with-channel.mdx
+++ b/apps/docs/AI/mcp/tools/share-with-channel.mdx
@@ -7,7 +7,7 @@ description: >-
# ShareWithChannel
-Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, chat, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists.
+Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists.
## Parameters
@@ -15,4 +15,4 @@ Share an item with the current members of a channel by writing a channel entity-
| --- | --- | --- | --- |
| `channelId` | string | Yes | Channel id whose current members should be able to view the item. |
| `entityId` | string | Yes | Id of the item to share. For a calendar chip this is the event id in documentId. |
-| `entityType` | `"calendar_event"` \| `"document"` \| `"chat"` \| `"project"` \| `"database"` \| `"form"` \| `"call"` \| `"thread"` \| `"agent_session"` | Yes | Entity types a channel grant can cover. Values are the stored entity types. `calendar` is accepted for a calendar chip, whose stored type is `calendar_event`. |
+| `entityType` | `"calendar_event"` \| `"document"` \| `"project"` \| `"database"` \| `"form"` \| `"call"` \| `"thread"` \| `"agent_session"` | Yes | Entity types a channel grant can cover. Values are the stored entity types. `calendar` is accepted for a calendar chip, whose stored type is `calendar_event`. |
diff --git a/apps/docs/AI/mcp/tools/update-agent-session-sharing.mdx b/apps/docs/AI/mcp/tools/update-agent-session-sharing.mdx
new file mode 100644
index 0000000000..c0567b8fc9
--- /dev/null
+++ b/apps/docs/AI/mcp/tools/update-agent-session-sharing.mdx
@@ -0,0 +1,19 @@
+---
+title: UpdateAgentSessionSharing
+description: >-
+ Change an agent session's link, team, or channel sharing as its owner.
+---
+
+# UpdateAgentSessionSharing
+
+Change an agent session's link, team, or channel sharing as its owner. Omitted settings remain unchanged; off revokes that grant. Requires an explicit user request to change sharing. Private persona conversations cannot be shared. Returns the resulting settings.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sessionId` | string | Yes | Session UUID. |
+| `linkScope` | `"off"` \| `"public"` \| `"team"` | No | Who the item's share link admits: public (anyone with the link), team (the owner's team members with the link), or off to disable link sharing. |
+| `linkAccess` | `"off"` \| `"view"` \| `"comment"` \| `"edit"` | No | Permission granted by an enabled share link. Off resets it to the default level. |
+| `teamAccess` | `"off"` \| `"view"` \| `"comment"` \| `"edit"` | No | Access for everyone on the owner's team; off removes it. |
+| `channels` | SessionSharingChannel[] | No | Individual channel grants to set or remove; other channel grants stay unchanged. |
diff --git a/apps/docs/AI/mcp/tools/update-sharing.mdx b/apps/docs/AI/mcp/tools/update-sharing.mdx
index 8620f0037d..c83017521f 100644
--- a/apps/docs/AI/mcp/tools/update-sharing.mdx
+++ b/apps/docs/AI/mcp/tools/update-sharing.mdx
@@ -1,20 +1,20 @@
---
title: UpdateSharing
description: >-
- Change who can access a document (including a task), an AI chat, or a project
- (folder), as the Share menu in the app does: link sharing, team access, and
- per-channel access.
+ Change who can access a document (including a task), or a project (folder), as
+ the Share menu in the app does: link sharing, team access, and per-channel
+ access.
---
# UpdateSharing
-Change who can access a document (including a task), an AI chat, or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning an AI chat or project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives).
+Change who can access a document (including a task), or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning a project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives).
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `entityType` | `"document"` \| `"chat"` \| `"project"` | Yes | The kind of item whose sharing changes. |
+| `entityType` | `"document"` \| `"project"` | Yes | The kind of item whose sharing changes. |
| `entityId` | string | Yes | The id of the item whose sharing changes. |
| `linkScope` | `"off"` \| `"public"` \| `"team"` | No | Who the item's share link admits: public (anyone with the link), team (the owner's team members with the link), or off to disable link sharing. |
| `linkAccess` | `"off"` \| `"view"` \| `"comment"` \| `"edit"` | No | Permission granted by an enabled share link. Off resets it to the default level. |
diff --git a/apps/docs/config/tool-pages.json b/apps/docs/config/tool-pages.json
index 553e48063a..003fc6902e 100644
--- a/apps/docs/config/tool-pages.json
+++ b/apps/docs/config/tool-pages.json
@@ -9,12 +9,13 @@
"AI/mcp/tools/configure-agent",
"AI/mcp/tools/configure-bot",
"AI/mcp/tools/content-search",
+ "AI/mcp/tools/create-agent-session",
"AI/mcp/tools/create-booking-link",
"AI/mcp/tools/create-bot",
"AI/mcp/tools/create-calendar-event",
"AI/mcp/tools/create-channel",
+ "AI/mcp/tools/create-channel-media-upload",
"AI/mcp/tools/create-company",
- "AI/mcp/tools/create-confirmed-calendar-event",
"AI/mcp/tools/create-contact",
"AI/mcp/tools/create-document",
"AI/mcp/tools/create-form",
@@ -37,9 +38,7 @@
"AI/mcp/tools/delete-routine",
"AI/mcp/tools/delete-tag",
"AI/mcp/tools/describe-database",
- "AI/mcp/tools/discover-connectors",
"AI/mcp/tools/dispatch-coding-agent",
- "AI/mcp/tools/display-results",
"AI/mcp/tools/duplicate-item",
"AI/mcp/tools/edit-booking-link",
"AI/mcp/tools/edit-channel-message",
@@ -87,7 +86,7 @@
"AI/mcp/tools/list-skills",
"AI/mcp/tools/list-tags",
"AI/mcp/tools/list-team-members",
- "AI/mcp/tools/load-tools",
+ "AI/mcp/tools/manage-agent-session",
"AI/mcp/tools/manage-bot-channel-access",
"AI/mcp/tools/manage-channel-participants",
"AI/mcp/tools/mark-notifications-done",
@@ -100,12 +99,13 @@
"AI/mcp/tools/query-database",
"AI/mcp/tools/react-to-channel-message",
"AI/mcp/tools/read-activity",
+ "AI/mcp/tools/read-agent-session",
+ "AI/mcp/tools/read-agent-session-sharing",
"AI/mcp/tools/read-booking-settings",
"AI/mcp/tools/read-call-record",
"AI/mcp/tools/read-channel-message-context",
"AI/mcp/tools/read-channel-messages",
"AI/mcp/tools/read-channel-thread",
- "AI/mcp/tools/read-chat",
"AI/mcp/tools/read-content",
"AI/mcp/tools/read-design",
"AI/mcp/tools/read-form",
@@ -119,7 +119,6 @@
"AI/mcp/tools/read-routine",
"AI/mcp/tools/read-skill",
"AI/mcp/tools/read-spreadsheet",
- "AI/mcp/tools/read-thread",
"AI/mcp/tools/read-word-document",
"AI/mcp/tools/remove-from-pipeline",
"AI/mcp/tools/rename-channel",
@@ -130,11 +129,8 @@
"AI/mcp/tools/save-database-query",
"AI/mcp/tools/save-database-view",
"AI/mcp/tools/search-skills",
- "AI/mcp/tools/search-tools",
"AI/mcp/tools/self-knowledge",
"AI/mcp/tools/send-channel-message",
- "AI/mcp/tools/send-confirmed-email",
- "AI/mcp/tools/send-email",
"AI/mcp/tools/set-entity-property",
"AI/mcp/tools/set-favorite",
"AI/mcp/tools/set-form-access",
@@ -142,6 +138,7 @@
"AI/mcp/tools/share-with-channel",
"AI/mcp/tools/subagent",
"AI/mcp/tools/text-editor-code-execution",
+ "AI/mcp/tools/update-agent-session-sharing",
"AI/mcp/tools/update-booking-settings",
"AI/mcp/tools/update-calendar-event",
"AI/mcp/tools/update-call-record",
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 5b63b89bfc..0e37114564 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -80,12 +80,13 @@
"AI/mcp/tools/configure-agent",
"AI/mcp/tools/configure-bot",
"AI/mcp/tools/content-search",
+ "AI/mcp/tools/create-agent-session",
"AI/mcp/tools/create-booking-link",
"AI/mcp/tools/create-bot",
"AI/mcp/tools/create-calendar-event",
"AI/mcp/tools/create-channel",
+ "AI/mcp/tools/create-channel-media-upload",
"AI/mcp/tools/create-company",
- "AI/mcp/tools/create-confirmed-calendar-event",
"AI/mcp/tools/create-contact",
"AI/mcp/tools/create-document",
"AI/mcp/tools/create-form",
@@ -108,9 +109,7 @@
"AI/mcp/tools/delete-routine",
"AI/mcp/tools/delete-tag",
"AI/mcp/tools/describe-database",
- "AI/mcp/tools/discover-connectors",
"AI/mcp/tools/dispatch-coding-agent",
- "AI/mcp/tools/display-results",
"AI/mcp/tools/duplicate-item",
"AI/mcp/tools/edit-booking-link",
"AI/mcp/tools/edit-channel-message",
@@ -158,7 +157,7 @@
"AI/mcp/tools/list-skills",
"AI/mcp/tools/list-tags",
"AI/mcp/tools/list-team-members",
- "AI/mcp/tools/load-tools",
+ "AI/mcp/tools/manage-agent-session",
"AI/mcp/tools/manage-bot-channel-access",
"AI/mcp/tools/manage-channel-participants",
"AI/mcp/tools/mark-notifications-done",
@@ -171,12 +170,13 @@
"AI/mcp/tools/query-database",
"AI/mcp/tools/react-to-channel-message",
"AI/mcp/tools/read-activity",
+ "AI/mcp/tools/read-agent-session",
+ "AI/mcp/tools/read-agent-session-sharing",
"AI/mcp/tools/read-booking-settings",
"AI/mcp/tools/read-call-record",
"AI/mcp/tools/read-channel-message-context",
"AI/mcp/tools/read-channel-messages",
"AI/mcp/tools/read-channel-thread",
- "AI/mcp/tools/read-chat",
"AI/mcp/tools/read-content",
"AI/mcp/tools/read-design",
"AI/mcp/tools/read-form",
@@ -190,7 +190,6 @@
"AI/mcp/tools/read-routine",
"AI/mcp/tools/read-skill",
"AI/mcp/tools/read-spreadsheet",
- "AI/mcp/tools/read-thread",
"AI/mcp/tools/read-word-document",
"AI/mcp/tools/remove-from-pipeline",
"AI/mcp/tools/rename-channel",
@@ -201,11 +200,8 @@
"AI/mcp/tools/save-database-query",
"AI/mcp/tools/save-database-view",
"AI/mcp/tools/search-skills",
- "AI/mcp/tools/search-tools",
"AI/mcp/tools/self-knowledge",
"AI/mcp/tools/send-channel-message",
- "AI/mcp/tools/send-confirmed-email",
- "AI/mcp/tools/send-email",
"AI/mcp/tools/set-entity-property",
"AI/mcp/tools/set-favorite",
"AI/mcp/tools/set-form-access",
@@ -213,6 +209,7 @@
"AI/mcp/tools/share-with-channel",
"AI/mcp/tools/subagent",
"AI/mcp/tools/text-editor-code-execution",
+ "AI/mcp/tools/update-agent-session-sharing",
"AI/mcp/tools/update-booking-settings",
"AI/mcp/tools/update-calendar-event",
"AI/mcp/tools/update-call-record",
diff --git a/apps/docs/scripts/generate-mcp-tool-pages.ts b/apps/docs/scripts/generate-mcp-tool-pages.ts
index f248cad418..91387a964d 100644
--- a/apps/docs/scripts/generate-mcp-tool-pages.ts
+++ b/apps/docs/scripts/generate-mcp-tool-pages.ts
@@ -12,7 +12,7 @@ type ToolEntry = {
output: string;
};
-/** Shape of `crates/ai_tools/schemas/tools.json`. */
+/** Shape of `crates/ai_tools/schemas/mcp-tools.json`. */
type ToolSchemaFile = {
$defs: Record<string, JsonSchema>;
tools: ToolEntry[];
@@ -29,7 +29,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
const docsDir = path.resolve(__dirname, '..');
const repoRoot = path.resolve(docsDir, '../..');
const aiToolsDir = path.join(repoRoot, 'crates', 'ai_tools');
-const toolJsonPath = path.join(aiToolsDir, 'schemas', 'tools.json');
+const toolJsonPath = path.join(aiToolsDir, 'schemas', 'mcp-tools.json');
const outputDir = path.join(docsDir, 'AI', 'mcp', 'tools');
const navOutputPath = path.join(docsDir, 'config', 'tool-pages.json');
const docsJsonPath = path.join(docsDir, 'docs.json');
@@ -186,10 +186,9 @@ ${rows.join('\n')}`;
}
async function buildAndRunSchemaGenerator() {
- await $`cd ${repoRoot} && SQLX_OFFLINE=true cargo build --bin gen_tool_schemas`;
- await $`rm -rf ${path.join(aiToolsDir, 'schemas')}`.quiet();
+ await $`SQLX_OFFLINE=true cargo build --bin gen_tool_schemas`.cwd(repoRoot);
const binaryPath = path.join(repoRoot, 'target', 'debug', 'gen_tool_schemas');
- await $`cd ${aiToolsDir} && ${binaryPath}`;
+ await $`${binaryPath} --mcp`.cwd(aiToolsDir);
}
async function loadSchemas(): Promise<ToolSchemaFile> {
@@ -313,10 +312,8 @@ async function writeNavigation(navPages: string[]) {
async function main() {
const file = await loadSchemas();
- // The shared frontend schemas also include tools from the private agent
- // session endpoint. They are unavailable through the public MCP server.
+ // Public MCP schemas omit historical frontend compatibility and private tools.
const tools = resolveTools(file)
- .filter((tool) => !['DescribeCodeTools', 'ExecuteCode'].includes(tool.name))
.sort((a, b) => a.name.localeCompare(b.name));
await resetGeneratedPages();
diff --git a/apps/web/src/features/block-agent/component/parts/MacroToolCall.tsx b/apps/web/src/features/block-agent/component/parts/MacroToolCall.tsx
index 11fc2d4b4c..e15f2d3b0b 100644
--- a/apps/web/src/features/block-agent/component/parts/MacroToolCall.tsx
+++ b/apps/web/src/features/block-agent/component/parts/MacroToolCall.tsx
@@ -213,6 +213,7 @@ function MacroToolIcon(props: { name: string }): JSX.Element {
'ReadMetadata',
'ReadThread',
'ReadChat',
+ 'ReadAgentSession',
'ReadProject',
'ReadPresentation',
'ReadDesign',
diff --git a/apps/web/src/features/block-agent/state/tool-approval-wording.ts b/apps/web/src/features/block-agent/state/tool-approval-wording.ts
index b62ef45a9a..ca8fa1e1e0 100644
--- a/apps/web/src/features/block-agent/state/tool-approval-wording.ts
+++ b/apps/web/src/features/block-agent/state/tool-approval-wording.ts
@@ -124,6 +124,11 @@ const MACRO_TOOLS: Record<MacroToolName, Wording | null> = {
ReadChannelMessageContext: (whose) => `read ${whose} channel messages`,
ReadChannelMessages: (whose) => `read ${whose} channel messages`,
ReadChannelThread: (whose) => `read ${whose} channel messages`,
+ CreateAgentSession: (whose) => `start an agent session with ${whose} access`,
+ ManageAgentSession: (whose) => `manage ${whose} agent sessions`,
+ ReadAgentSessionSharing: (whose) => `read ${whose} session sharing`,
+ UpdateAgentSessionSharing: (whose) => `change ${whose} session sharing`,
+ ReadAgentSession: (whose) => `read ${whose} agent sessions`,
ReadChat: (whose) => `read ${whose} chats`,
ReadContent: (whose) => `read ${whose} documents`,
ReadDesign: (whose) => `read ${whose} designs`,
diff --git a/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.test.tsx b/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.test.tsx
new file mode 100644
index 0000000000..c5794622e7
--- /dev/null
+++ b/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.test.tsx
@@ -0,0 +1,63 @@
+import type { MagicChipData } from '@macro-inc/lexical-core';
+import { cleanup, render } from '@solidjs/testing-library';
+import { afterEach, expect, it, vi } from 'vitest';
+import {
+ createAgentSessionHandler,
+ manageAgentSessionHandler,
+} from './AgentSessionActions';
+import { ToolErrorContext } from './ToolRenderer';
+
+vi.mock('../../../LexicalMarkdown/component/decorator/MagicChip', () => ({
+ MagicChip: (props: MagicChipData) => (
+ <div data-testid="session" data-session={props.agentSessionId} />
+ ),
+}));
+afterEach(cleanup);
+const id = '0195d721-1730-7cda-a72e-855bec53411e';
+const context = {
+ chat_id: 'chat',
+ message_id: 'message',
+ part_index: 0,
+ isComplete: true,
+ renderContext: { isStreaming: false, followedBy: () => false },
+};
+
+it('links the created session instead of showing its raw response', () => {
+ const view = render(() => (
+ <createAgentSessionHandler.render
+ {...context}
+ tool={{
+ id,
+ name: 'CreateAgentSession',
+ data: { agentId: id, prompt: 'Research this topic' },
+ }}
+ response={{
+ id,
+ name: 'CreateAgentSession',
+ data: { agent_id: id, agent_session_id: id, agent_name: 'Researcher' },
+ }}
+ />
+ ));
+ expect(view.getByTestId('session').dataset.session).toBe(id);
+ expect(view.queryByRole('status')).toBeNull();
+});
+
+it('does not present an uncertain prompt as completed work', () => {
+ const view = render(() => (
+ <ToolErrorContext.Provider value={() => 'delivery unknown'}>
+ <manageAgentSessionHandler.render
+ {...context}
+ tool={{
+ id,
+ name: 'ManageAgentSession',
+ data: {
+ sessionId: id,
+ action: { type: 'prompt', prompt: 'Continue' },
+ },
+ }}
+ />
+ </ToolErrorContext.Provider>
+ ));
+ expect(view.getByText('Could not confirm')).toBeTruthy();
+ expect(view.queryByText('Complete')).toBeNull();
+});
diff --git a/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.tsx b/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.tsx
new file mode 100644
index 0000000000..0e83ddab41
--- /dev/null
+++ b/apps/web/src/lib/core/component/AI/component/tool/AgentSessionActions.tsx
@@ -0,0 +1,143 @@
+import Robot from '@phosphor-icons/core/regular/robot.svg';
+import type { ToolName } from '@service-cognition/generated/tools/tool';
+import { createSignal, For, Show, Suspense } from 'solid-js';
+import { MagicChip } from '../../../LexicalMarkdown/component/decorator/MagicChip';
+import { BaseTool } from './BaseTool';
+import { Tool } from './Tool';
+import { createToolRenderer, useToolError } from './ToolRenderer';
+
+type SharingTool = Extract<
+ ToolName,
+ 'ReadAgentSessionSharing' | 'UpdateAgentSessionSharing'
+>;
+function sharingHandler<T extends SharingTool>(name: T, label: string) {
+ return createToolRenderer({
+ name,
+ render: (ctx) => {
+ const [expanded, setExpanded] = createSignal(false);
+ const error = () => useToolError();
+ return (
+ <BaseTool
+ icon={Robot}
+ renderContext={ctx.renderContext}
+ type="call"
+ response={
+ <Show when={expanded() && ctx.response?.data}>
+ {(settings) => (
+ <div class="space-y-2 p-3 text-xs">
+ <p>
+ Link access:{' '}
+ {settings().linkScope === 'off'
+ ? 'Off'
+ : `${settings().linkScope} · ${settings().linkAccess ?? 'view'}`}
+ </p>
+ <p>Team access: {settings().teamAccess ?? 'Off'}</p>
+ <For
+ each={settings().channels}
+ fallback={<p>No channel grants</p>}
+ >
+ {(grant) => (
+ <p class="break-words">
+ Channel {grant.channelId}: {grant.access}
+ </p>
+ )}
+ </For>
+ </div>
+ )}
+ </Show>
+ }
+ >
+ <div class="flex min-w-0 flex-1 items-center justify-between gap-3">
+ <span>{label}</span>
+ <Tool.ResultToggle
+ expanded={expanded()}
+ onToggle={() => setExpanded((value) => !value)}
+ showToggle={!!ctx.response}
+ status={
+ error()
+ ? 'Could not confirm'
+ : ctx.response
+ ? 'Complete'
+ : undefined
+ }
+ />
+ </div>
+ </BaseTool>
+ );
+ },
+ });
+}
+export const createAgentSessionHandler = createToolRenderer({
+ name: 'CreateAgentSession',
+ render: (ctx) => {
+ const error = () => useToolError();
+ return (
+ <Show
+ when={ctx.response?.data}
+ fallback={
+ <p role="status" class="py-2 text-sm text-ink-muted">
+ {error()
+ ? 'Could not confirm session creation'
+ : 'Starting agent session…'}
+ </p>
+ }
+ >
+ {(result) => (
+ <Suspense fallback={<p role="status">Loading agent session…</p>}>
+ <MagicChip
+ agentSessionId={result().agent_session_id}
+ promptedMessage={{ turn: 0, author: 'user' }}
+ status="booting"
+ />
+ </Suspense>
+ )}
+ </Show>
+ );
+ },
+});
+export const manageAgentSessionHandler = createToolRenderer({
+ name: 'ManageAgentSession',
+ render: (ctx) => {
+ const error = () => useToolError();
+ const label = () => {
+ switch (ctx.tool.data.action.type) {
+ case 'rename':
+ return 'Rename agent session';
+ case 'archive':
+ return ctx.tool.data.action.archived
+ ? 'Archive agent session'
+ : 'Unarchive agent session';
+ case 'delete':
+ return 'Delete agent session';
+ case 'prompt':
+ return 'Send prompt to agent';
+ case 'stop':
+ return 'Stop agent';
+ }
+ };
+ const status = () => {
+ if (error()) return 'Could not confirm';
+ const result = ctx.response?.data;
+ if (!result) return undefined;
+ if (result.status === 'queued') return 'Queued';
+ if (result.status === 'sent') return 'Sent';
+ return result.message;
+ };
+ return (
+ <BaseTool icon={Robot} renderContext={ctx.renderContext} type="call">
+ <div class="flex min-w-0 flex-1 items-center justify-between gap-3">
+ <span>{label()}</span>
+ <span class="text-ink-muted">{status()}</span>
+ </div>
+ </BaseTool>
+ );
+ },
+});
+export const readAgentSessionSharingHandler = sharingHandler(
+ 'ReadAgentSessionSharing',
+ 'Read session sharing'
+);
+export const updateAgentSessionSharingHandler = sharingHandler(
+ 'UpdateAgentSessionSharing',
+ 'Update session sharing'
+);
diff --git a/apps/web/src/lib/core/component/AI/component/tool/LegacyConversationTools.test.ts b/apps/web/src/lib/core/component/AI/component/tool/LegacyConversationTools.test.ts
new file mode 100644
index 0000000000..d61d8ef4c8
--- /dev/null
+++ b/apps/web/src/lib/core/component/AI/component/tool/LegacyConversationTools.test.ts
@@ -0,0 +1,87 @@
+import {
+ deserializeToolCall,
+ deserializeToolResponse,
+} from '@service-cognition/generated/tools/tool';
+import { describe, expect, it } from 'vitest';
+
+const id = '0195d721-1730-7cda-a72e-855bec53411e';
+
+describe('saved legacy conversation tool records', () => {
+ it('keeps old mixed listings readable', () => {
+ expect(
+ deserializeToolCall({
+ id,
+ name: 'ListEntities',
+ json: { includeTypes: ['ai_chat'] },
+ }).isOk()
+ ).toBe(true);
+ const result = deserializeToolResponse({
+ id,
+ name: 'ListEntities',
+ json: {
+ items: [
+ { type: 'aiChat', id, name: 'Saved conversation' },
+ {
+ type: 'document',
+ id,
+ name: 'Notes',
+ fileType: 'md',
+ subType: null,
+ },
+ ],
+ summary: '2 items',
+ hasMore: false,
+ },
+ });
+ expect(result.isOk()).toBe(true);
+ if (result.isOk()) {
+ expect(result.value.data).toHaveProperty('items.length', 2);
+ }
+ });
+
+ it('keeps old folder results and mutation records readable', () => {
+ expect(
+ deserializeToolResponse({
+ id,
+ name: 'ReadProject',
+ json: {
+ projectId: id,
+ projectName: 'Folder',
+ parentProjectId: null,
+ items: [
+ {
+ id,
+ itemType: 'chat',
+ name: 'Saved conversation',
+ fileType: null,
+ updatedAt: null,
+ },
+ ],
+ },
+ }).isOk()
+ ).toBe(true);
+ for (const name of ['RenameItem', 'MoveToTrash', 'SetFavorite'] as const) {
+ const data = {
+ entityType: 'chat',
+ entityId: id,
+ name: 'Renamed',
+ favorite: true,
+ };
+ expect(deserializeToolCall({ id, name, json: data }).isOk()).toBe(true);
+ }
+ expect(
+ deserializeToolResponse({
+ id,
+ name: 'RenameItem',
+ json: { entityType: 'chat', entityId: id, name: 'Renamed' },
+ }).isOk()
+ ).toBe(true);
+ expect(
+ deserializeToolCall({
+ id,
+ name: 'NameSearch',
+ json: { name: 'saved', entityTypes: ['chats'] },
+ }).isOk()
+ ).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/core/component/AI/component/tool/ListEntities.tsx b/apps/web/src/lib/core/component/AI/component/tool/ListEntities.tsx
index 207967c096..54b16b76a3 100644
--- a/apps/web/src/lib/core/component/AI/component/tool/ListEntities.tsx
+++ b/apps/web/src/lib/core/component/AI/component/tool/ListEntities.tsx
@@ -33,7 +33,8 @@ const ListEntitiesToolResponse = (props: {
case 'document':
return item.name || 'Document';
case 'aiChat':
- return item.name || 'Chat';
+ case 'agentSession':
+ return item.name || 'Agent session';
case 'project':
return item.name || 'Project';
case 'email':
@@ -61,7 +62,8 @@ const ListEntitiesToolResponse = (props: {
/>
);
case 'aiChat':
- return <EntityIcon targetType="chat" size="xs" theme="monochrome" />;
+ case 'agentSession':
+ return <EntityIcon targetType="agent" size="xs" theme="monochrome" />;
case 'project':
return <EntityIcon targetType="project" size="xs" theme="monochrome" />;
case 'email':
@@ -92,6 +94,13 @@ const ListEntitiesToolResponse = (props: {
{ activate: true, preferNewSplit: event.shiftKey }
);
};
+ case 'agentSession':
+ return (event: MouseEvent) => {
+ openWithSplit(
+ { type: 'agent', id: item.id },
+ { activate: true, preferNewSplit: event.shiftKey }
+ );
+ };
case 'project':
return (event: MouseEvent) => {
openWithSplit(
diff --git a/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.test.tsx b/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.test.tsx
new file mode 100644
index 0000000000..ba44a2c8b5
--- /dev/null
+++ b/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.test.tsx
@@ -0,0 +1,54 @@
+import { cleanup, fireEvent, render } from '@solidjs/testing-library';
+import { afterEach, expect, it } from 'vitest';
+import { readAgentSessionHandler } from './ReadAgentSession';
+
+afterEach(cleanup);
+
+it('expands the conversation and preserves the failure when text was truncated', () => {
+ const view = render(() => (
+ <readAgentSessionHandler.render
+ tool={{
+ id: 'read-1',
+ name: 'ReadAgentSession',
+ data: { sessionId: '0195d721-1730-7cda-a72e-855bec53411e' },
+ }}
+ response={{
+ id: 'read-1',
+ name: 'ReadAgentSession',
+ data: {
+ sessionId: '0195d721-1730-7cda-a72e-855bec53411e',
+ name: 'Debug session',
+ ownerId: 'macro|[email protected]',
+ botId: 'bot-id',
+ isArchived: false,
+ harness: 'in-memory',
+ model: 'test',
+ status: 'disconnected',
+ totalMessages: 2,
+ truncated: true,
+ messages: [
+ {
+ turn: 0,
+ role: 'agent',
+ content: 'Checking the integration',
+ truncated: true,
+ failure: 'Unknown tool mcp__missing',
+ },
+ ],
+ },
+ }}
+ chat_id="chat-1"
+ message_id="message-1"
+ part_index={0}
+ isComplete={true}
+ renderContext={{ isStreaming: false, followedBy: () => false }}
+ />
+ ));
+ expect(view.queryByText('Checking the integration')).toBeNull();
+ fireEvent.click(view.getByRole('button', { name: /1 messages/ }));
+ expect(view.getByText('Checking the integration')).toBeTruthy();
+ expect(view.getByText('Failed: Unknown tool mcp__missing')).toBeTruthy();
+ expect(view.getByText('Message truncated')).toBeTruthy();
+ fireEvent.click(view.getByRole('button', { name: /1 messages/ }));
+ expect(view.queryByText('Checking the integration')).toBeNull();
+});
diff --git a/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.tsx b/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.tsx
new file mode 100644
index 0000000000..dd017a2fc8
--- /dev/null
+++ b/apps/web/src/lib/core/component/AI/component/tool/ReadAgentSession.tsx
@@ -0,0 +1,69 @@
+import Newspaper from '@phosphor-icons/core/regular/newspaper.svg';
+import { createSignal, For, Show } from 'solid-js';
+import { BaseTool } from './BaseTool';
+import { Tool } from './Tool';
+import { createToolRenderer } from './ToolRenderer';
+
+export const readAgentSessionHandler = createToolRenderer({
+ name: 'ReadAgentSession',
+ render: (ctx) => {
+ const [expanded, setExpanded] = createSignal(false);
+ const response = () => ctx.response?.data;
+ return (
+ <BaseTool
+ icon={Newspaper}
+ renderContext={ctx.renderContext}
+ type="call"
+ response={
+ <Show when={expanded() && response()}>
+ {(result) => (
+ <div class="max-h-96 overflow-auto space-y-3 p-3">
+ <p class="text-ink-muted">
+ {result().name} · {result().status}
+ {result().isArchived ? ' · Archived' : ''}
+ </p>
+ <Show when={result().truncated}>
+ <p class="text-ink-muted">
+ Some history or message text was omitted.
+ </p>
+ </Show>
+ <For each={result().messages}>
+ {(message) => (
+ <div>
+ <div class="text-ink-muted">
+ {message.role} · Turn {message.turn}
+ </div>
+ <pre class="whitespace-pre-wrap break-words font-sans">
+ {message.content}
+ </pre>
+ <Show when={message.truncated}>
+ <span class="text-ink-muted">Message truncated</span>
+ </Show>
+ <Show when={message.failure}>
+ {(failure) => (
+ <p class="whitespace-pre-wrap break-words">
+ Failed: {failure()}
+ </p>
+ )}
+ </Show>
+ </div>
+ )}
+ </For>
+ </div>
+ )}
+ </Show>
+ }
+ >
+ <span class="min-w-0 flex-1">Read agent session</span>
+ <Tool.ResultToggle
+ expanded={expanded()}
+ onToggle={() => setExpanded((value) => !value)}
+ showToggle={!!response()}
+ status={
+ response() ? `${response()?.messages.length} messages` : undefined
+ }
+ />
+ </BaseTool>
+ );
+ },
+});
diff --git a/apps/web/src/lib/core/component/AI/component/tool/handler.tsx b/apps/web/src/lib/core/component/AI/component/tool/handler.tsx
index 4d47a290d6..7ec476284f 100644
--- a/apps/web/src/lib/core/component/AI/component/tool/handler.tsx
+++ b/apps/web/src/lib/core/component/AI/component/tool/handler.tsx
@@ -14,6 +14,12 @@ import {
} from '@service-cognition/generated/tools/tool';
import { createMemo, Show } from 'solid-js';
import { Dynamic } from 'solid-js/web';
+import {
+ createAgentSessionHandler,
+ manageAgentSessionHandler,
+ readAgentSessionSharingHandler,
+ updateAgentSessionSharingHandler,
+} from './AgentSessionActions';
import { configureAgentHandler, listAgentsHandler } from './Agents';
import { bashCodeExecutionHandler } from './BashCodeExecution';
import {
@@ -133,6 +139,7 @@ import {
setEntityPropertyHandler,
} from './Properties';
import { readActivityHandler } from './ReadActivity';
+import { readAgentSessionHandler } from './ReadAgentSession';
import { readCallRecordHandler } from './ReadCallRecord';
import {
readChannelMessageContextHandler,
@@ -293,6 +300,11 @@ const toolHandlers: ToolHandlerMap<RenderContext> = {
ReadChannelMessages: readChannelMessagesHandler,
ReadChannelThread: readChannelThreadHandler,
ReadChat: readChatHandler,
+ ReadAgentSession: readAgentSessionHandler,
+ CreateAgentSession: createAgentSessionHandler,
+ ManageAgentSession: manageAgentSessionHandler,
+ ReadAgentSessionSharing: readAgentSessionSharingHandler,
+ UpdateAgentSessionSharing: updateAgentSessionSharingHandler,
ReadThread: readThreadHandler,
ReadContent: readContentHandler,
ReadMetadata: readMetadataHandler,
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
index 9be507a316..a62aafcc27 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
@@ -125,12 +125,12 @@ export const BulkSetEntityPropertyOptions = z.object({
'document',
'initiative',
'project',
- 'chat',
'thread',
'channel',
'call',
'user',
'company',
+ 'chat',
]),
entity_id: z.string(),
})
@@ -1163,12 +1163,12 @@ export const ContentSearch = z.object({
z.enum([
'agent_sessions',
'documents',
- 'chats',
'emails',
'channels',
'projects',
'call_records',
'calendar_events',
+ 'chats',
])
)
.optional(),
@@ -1343,56 +1343,6 @@ export const SearchToolResponse = z.object({
}),
z.object({ type: z.literal('document') })
),
- z.intersection(
- z.object({
- metadata: z
- .union([
- z.object({
- created_at: z.string().datetime({ offset: true }),
- updated_at: z.string().datetime({ offset: true }),
- viewed_at: z
- .union([
- z.string().datetime({ offset: true }),
- z.null(),
- ])
- .optional(),
- project_id: z.union([z.string(), z.null()]).optional(),
- deleted_at: z
- .union([
- z.string().datetime({ offset: true }),
- z.null(),
- ])
- .optional(),
- }),
- z.null(),
- ])
- .optional(),
- id: z.string().uuid(),
- name: z.string(),
- owner_id: z.string(),
- chat_id: z.string().uuid(),
- user_id: z.string(),
- chat_search_results: z.array(
- z.object({
- chat_message_id: z
- .union([z.string().uuid(), z.null()])
- .optional(),
- role: z.union([z.string(), z.null()]).optional(),
- highlight: z.object({
- name: z.union([z.string(), z.null()]).optional(),
- content: z.array(z.string()).optional(),
- user_id: z.union([z.string(), z.null()]).optional(),
- sender: z.union([z.string(), z.null()]).optional(),
- recipients: z.array(z.string()).optional(),
- cc: z.array(z.string()).optional(),
- bcc: z.array(z.string()).optional(),
- }),
- score: z.union([z.number(), z.null()]).optional(),
- })
- ),
- }),
- z.object({ type: z.literal('chat') })
- ),
z.intersection(
z.object({
created_at: z.string().datetime({ offset: true }),
@@ -1859,6 +1809,16 @@ export const SearchToolResponse = z.object({
),
});
+export const CreateAgentSession = z
+ .object({ agentId: z.string().uuid(), prompt: z.string() })
+ .strict();
+
+export const DispatchedCodingAgent = z.object({
+ agent_session_id: z.string().uuid(),
+ agent_id: z.string().uuid(),
+ agent_name: z.string(),
+});
+
export const CreateBookingLink = z
.object({
teamId: z.union([z.string().uuid(), z.null()]).optional(),
@@ -4546,12 +4506,6 @@ export const DispatchCodingAgent = z
.object({ agent_id: z.string().uuid(), prompt: z.string() })
.strict();
-export const DispatchedCodingAgent = z.object({
- agent_session_id: z.string().uuid(),
- agent_id: z.string().uuid(),
- agent_name: z.string(),
-});
-
export const DisplayResults = z.object({ view: z.any() });
export const DisplayResultsResponse = z.object({ message: z.string() });
@@ -8747,12 +8701,12 @@ export const GetEntityProperties = z.object({
'document',
'initiative',
'project',
- 'chat',
'thread',
'channel',
'call',
'user',
'company',
+ 'chat',
]),
});
@@ -9607,13 +9561,14 @@ export const ListEntities = z.object({
const schemas = [
z.literal('calendar_event'),
z.literal('document'),
- z.literal('ai_chat'),
+ z.literal('agent_session'),
z.literal('project'),
z.literal('email'),
z.literal('channel'),
z.literal('channel_thread'),
z.literal('call'),
z.literal('foreign_entity'),
+ z.literal('ai_chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -9663,7 +9618,7 @@ export const ListEntities = z.object({
.optional(),
df: z.any().optional(),
pf: z.any().optional(),
- cf: z.any().optional(),
+ asf: z.any().optional(),
emailPreset: z.union([z.literal('signal'), z.null()]).optional(),
ef: z.any().optional(),
chanf: z.any().optional(),
@@ -9807,33 +9762,13 @@ export const ListEntitiesResponse = z.object({
z.object({
id: z.string().uuid(),
name: z.string(),
- tags: z
- .array(
- z.object({
- label: z.string(),
- scope: z.any().superRefine((x, ctx) => {
- const schemas = [z.literal('personal'), z.literal('team')];
- const errors = schemas.reduce<z.ZodError[]>(
- (errors, schema) =>
- ((result) =>
- result.error ? [...errors, result.error] : errors)(
- schema.safeParse(x)
- ),
- []
- );
- if (schemas.length - errors.length !== 1) {
- ctx.addIssue({
- path: ctx.path,
- code: 'invalid_union',
- unionErrors: errors,
- message: 'Invalid input: Should pass single schema',
- });
- }
- }),
- })
- )
- .optional(),
- type: z.literal('aiChat'),
+ ownerId: z.string(),
+ botId: z.string().uuid(),
+ isArchived: z.boolean(),
+ status: z.string(),
+ turnState: z.union([z.string(), z.null()]).optional(),
+ repoUrl: z.union([z.string(), z.null()]).optional(),
+ type: z.literal('agentSession'),
}),
z.object({
id: z.string().uuid(),
@@ -9951,6 +9886,37 @@ export const ListEntitiesResponse = z.object({
metadata: z.any(),
type: z.literal('foreignEntity'),
}),
+ z.object({
+ type: z.literal('aiChat'),
+ id: z.string().uuid(),
+ name: z.string(),
+ tags: z
+ .array(
+ z.object({
+ label: z.string(),
+ scope: z.any().superRefine((x, ctx) => {
+ const schemas = [z.literal('personal'), z.literal('team')];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) =>
+ result.error ? [...errors, result.error] : errors)(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ })
+ )
+ .optional(),
+ }),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -10327,20 +10293,37 @@ export const ListNotifications = z.object({
includeTypes: z
.union([
z.array(
- z.enum([
- 'email',
- 'message',
- 'channel',
- 'document',
- 'project',
- 'chat',
- 'call',
- 'task',
- 'github',
- 'reminder',
- 'calendar',
- 'agent',
- ])
+ z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.literal('email'),
+ z.literal('message'),
+ z.literal('channel'),
+ z.literal('document'),
+ z.literal('project'),
+ z.literal('call'),
+ z.literal('task'),
+ z.literal('github'),
+ z.literal('reminder'),
+ z.literal('calendar'),
+ z.literal('agent'),
+ z.literal('chat'),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ })
),
z.null(),
])
@@ -10350,8 +10333,8 @@ export const ListNotifications = z.object({
z.array(
z.object({
entityType: z.enum([
+ 'agent_session',
'user',
- 'chat',
'channel',
'channel_message',
'document',
@@ -10367,6 +10350,7 @@ export const ListNotifications = z.object({
'reminder',
'skill',
'scheduled_action',
+ 'chat',
]),
id: z.string(),
})
@@ -10577,6 +10561,67 @@ export const LoadToolsResponse = z.object({
not_found: z.array(z.string()),
});
+export const ManageAgentSession = z
+ .object({
+ sessionId: z.string().uuid(),
+ action: z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.object({ name: z.string(), type: z.literal('rename') }).strict(),
+ z
+ .object({ archived: z.boolean(), type: z.literal('archive') })
+ .strict(),
+ z.object({ type: z.literal('delete') }).strict(),
+ z.object({ prompt: z.string(), type: z.literal('prompt') }).strict(),
+ z.object({ type: z.literal('stop') }).strict(),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ })
+ .strict();
+
+export const SessionActionResult = z.object({
+ sessionId: z.string().uuid(),
+ message: z.string(),
+ actionId: z.union([z.string().uuid(), z.null()]).optional(),
+ status: z
+ .union([
+ z.any().superRefine((x, ctx) => {
+ const schemas = [z.literal('sent'), z.literal('queued')];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ z.null(),
+ ])
+ .optional(),
+});
+
export const ManageBotChannelAccess = z.object({
botId: z.string().uuid(),
channelId: z.string().uuid(),
@@ -10689,9 +10734,9 @@ export const MoveToProject = z.object({
entityType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('email'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -10722,8 +10767,8 @@ export const MoveToTrash = z.object({
entityType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -10748,8 +10793,8 @@ export const MoveToTrashResponse = z.object({
entityType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -10773,8 +10818,8 @@ export const MoveToTrashResponse = z.object({
export const MuteNotifications = z.object({
entityType: z.enum([
+ 'agent_session',
'user',
- 'chat',
'channel',
'channel_message',
'document',
@@ -10790,6 +10835,7 @@ export const MuteNotifications = z.object({
'reminder',
'skill',
'scheduled_action',
+ 'chat',
]),
entityId: z.string(),
action: z.any().superRefine((x, ctx) => {
@@ -10878,12 +10924,12 @@ export const NameSearch = z.object({
z.enum([
'agent_sessions',
'documents',
- 'chats',
'emails',
'channels',
'projects',
'call_records',
'calendar_events',
+ 'chats',
])
)
.optional(),
@@ -11305,6 +11351,90 @@ export const ReadActivityResponse = z.object({
truncated: z.boolean(),
});
+export const ReadAgentSession = z
+ .object({
+ sessionId: z.string().uuid(),
+ turn: z.union([z.number().int().gte(0), z.null()]).optional(),
+ })
+ .strict();
+
+export const SessionConversation = z.object({
+ sessionId: z.string().uuid(),
+ name: z.string(),
+ ownerId: z.string(),
+ botId: z.string().uuid(),
+ isArchived: z.boolean(),
+ harness: z.string(),
+ model: z.string(),
+ status: z.string(),
+ messages: z.array(
+ z.object({
+ turn: z.number().int().gte(0),
+ role: z.any().superRefine((x, ctx) => {
+ const schemas = [z.literal('user'), z.literal('agent')];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ content: z.string(),
+ failure: z.union([z.string(), z.null()]).optional(),
+ truncated: z.boolean(),
+ })
+ ),
+ totalMessages: z.number().int().gte(0),
+ truncated: z.boolean(),
+});
+
+export const ReadAgentSessionSharing = z
+ .object({ sessionId: z.string().uuid() })
+ .strict();
+
+export const SessionSharingResponse = z.object({
+ owner: z.string(),
+ linkScope: z.any().superRefine((x, ctx) => {
+ const schemas = [z.literal('off'), z.literal('public'), z.literal('team')];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ linkAccess: z
+ .union([z.enum(['view', 'comment', 'edit', 'owner']), z.null()])
+ .optional(),
+ teamAccess: z
+ .union([z.enum(['view', 'comment', 'edit', 'owner']), z.null()])
+ .optional(),
+ channels: z.array(
+ z.object({
+ channelId: z.string(),
+ access: z.enum(['view', 'comment', 'edit', 'owner']),
+ })
+ ),
+});
+
export const ReadBookingSettings = z
.object({ teamId: z.union([z.string().uuid(), z.null()]).optional() })
.strict();
@@ -12223,20 +12353,6 @@ export const ReadChannelThreadResponse = z.object({
),
});
-export const ReadChat = z.object({ chatId: z.string() });
-
-export const ReadChatResponse = z.object({
- chatId: z.string(),
- title: z.string(),
- messages: z.array(
- z.object({
- role: z.string(),
- content: z.string(),
- attachmentIds: z.array(z.string()),
- })
- ),
-});
-
export const ReadContent = z.object({ documentId: z.string().uuid() });
export const ReadContentResponse = z.object({
@@ -13770,8 +13886,8 @@ export const ReadProjectResponse = z.object({
itemType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -14571,12 +14687,12 @@ export const SetEntityProperty = z.object({
'document',
'initiative',
'project',
- 'chat',
'thread',
'channel',
'call',
'user',
'company',
+ 'chat',
]),
property_definition_id: z.string().uuid(),
boolean_value: z.union([z.boolean(), z.null()]).optional(),
@@ -14597,13 +14713,13 @@ export const SetEntityProperty = z.object({
'task',
'initiative',
'project',
- 'chat',
'thread',
'channel',
'call',
'user',
'company',
'contact',
+ 'chat',
]),
entityId: z.string(),
}),
@@ -14619,13 +14735,13 @@ export const SetEntityProperty = z.object({
'task',
'initiative',
'project',
- 'chat',
'thread',
'channel',
'call',
'user',
'company',
'contact',
+ 'chat',
]),
entityId: z.string(),
})
@@ -14647,12 +14763,12 @@ export const SetFavorite = z.object({
const schemas = [
z.literal('document'),
z.literal('project'),
- z.literal('chat'),
z.literal('channel'),
z.literal('email'),
z.literal('call'),
z.literal('crm_company'),
z.literal('crm_contact'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -14679,12 +14795,12 @@ export const SetFavoriteResponse = z.object({
const schemas = [
z.literal('document'),
z.literal('project'),
- z.literal('chat'),
z.literal('channel'),
z.literal('email'),
z.literal('call'),
z.literal('crm_company'),
z.literal('crm_contact'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -14872,13 +14988,13 @@ export const ShareWithChannel = z.object({
const schemas = [
z.literal('calendar_event'),
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
z.literal('database'),
z.literal('form'),
z.literal('call'),
z.literal('thread'),
z.literal('agent_session'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -14905,13 +15021,13 @@ export const ShareWithChannelResponse = z.object({
const schemas = [
z.literal('calendar_event'),
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
z.literal('database'),
z.literal('form'),
z.literal('call'),
z.literal('thread'),
z.literal('agent_session'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -15047,6 +15163,129 @@ export const TextEditorCodeExecutionResponse = z.object({
}),
});
+export const UpdateAgentSessionSharing = z
+ .object({
+ sessionId: z.string().uuid(),
+ linkScope: z
+ .union([
+ z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.literal('off'),
+ z.literal('public'),
+ z.literal('team'),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ z.null(),
+ ])
+ .optional(),
+ linkAccess: z
+ .union([
+ z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.literal('off'),
+ z.literal('view'),
+ z.literal('comment'),
+ z.literal('edit'),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ z.null(),
+ ])
+ .optional(),
+ teamAccess: z
+ .union([
+ z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.literal('off'),
+ z.literal('view'),
+ z.literal('comment'),
+ z.literal('edit'),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) => (result.error ? [...errors, result.error] : errors))(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ z.null(),
+ ])
+ .optional(),
+ channels: z
+ .union([
+ z.array(
+ z.object({
+ channelId: z.string().uuid(),
+ access: z.any().superRefine((x, ctx) => {
+ const schemas = [
+ z.literal('off'),
+ z.literal('view'),
+ z.literal('comment'),
+ z.literal('edit'),
+ ];
+ const errors = schemas.reduce<z.ZodError[]>(
+ (errors, schema) =>
+ ((result) =>
+ result.error ? [...errors, result.error] : errors)(
+ schema.safeParse(x)
+ ),
+ []
+ );
+ if (schemas.length - errors.length !== 1) {
+ ctx.addIssue({
+ path: ctx.path,
+ code: 'invalid_union',
+ unionErrors: errors,
+ message: 'Invalid input: Should pass single schema',
+ });
+ }
+ }),
+ })
+ ),
+ z.null(),
+ ])
+ .optional(),
+ })
+ .strict();
+
export const UpdateBookingSettings = z
.object({
teamId: z.union([z.string().uuid(), z.null()]).optional(),
@@ -15576,8 +15815,8 @@ export const UpdateSharing = z.object({
entityType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -15719,8 +15958,8 @@ export const UpdateSharingResponse = z.object({
entityType: z.any().superRefine((x, ctx) => {
const schemas = [
z.literal('document'),
- z.literal('chat'),
z.literal('project'),
+ z.literal('chat'),
];
const errors = schemas.reduce<z.ZodError[]>(
(errors, schema) =>
@@ -15996,6 +16235,20 @@ export const ExecutionReceipt = z.object({
error: z.union([z.string(), z.null()]).optional(),
});
+export const ReadChat = z.object({ chatId: z.string() });
+
+export const ReadChatResponse = z.object({
+ chatId: z.string(),
+ title: z.string(),
+ messages: z.array(
+ z.object({
+ role: z.string(),
+ content: z.string(),
+ attachmentIds: z.array(z.string()),
+ })
+ ),
+});
+
export const ReadThread = z.object({
contentType: z.enum([
'channel',
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts
index f3cd6fbfb2..80b95ca599 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts
@@ -42,6 +42,10 @@ type ToolParserMap = {
call: types.ContentSearch;
response: types.SearchToolResponse;
};
+ CreateAgentSession: {
+ call: types.CreateAgentSession;
+ response: types.DispatchedCodingAgent;
+ };
CreateBookingLink: {
call: types.CreateBookingLink;
response: types.BookingLinkResult;
@@ -294,6 +298,10 @@ type ToolParserMap = {
response: types.ListTeamMembersResponse;
};
LoadTools: { call: types.LoadTools; response: types.LoadToolsResponse };
+ ManageAgentSession: {
+ call: types.ManageAgentSession;
+ response: types.SessionActionResult;
+ };
ManageBotChannelAccess: {
call: types.ManageBotChannelAccess;
response: types.ManageBotChannelAccessResponse;
@@ -336,6 +344,14 @@ type ToolParserMap = {
call: types.ReadActivity;
response: types.ReadActivityResponse;
};
+ ReadAgentSession: {
+ call: types.ReadAgentSession;
+ response: types.SessionConversation;
+ };
+ ReadAgentSessionSharing: {
+ call: types.ReadAgentSessionSharing;
+ response: types.SessionSharingResponse;
+ };
ReadBookingSettings: {
call: types.ReadBookingSettings;
response: types.BookingSettingsResult;
@@ -462,6 +478,10 @@ type ToolParserMap = {
call: types.TextEditorCodeExecution;
response: types.TextEditorCodeExecutionResponse;
};
+ UpdateAgentSessionSharing: {
+ call: types.UpdateAgentSessionSharing;
+ response: types.SessionSharingResponse;
+ };
UpdateBookingSettings: {
call: types.UpdateBookingSettings;
response: types.BookingSettingsResult;
@@ -534,6 +554,10 @@ const toolParserMap = {
call: schemas.ContentSearch,
response: schemas.SearchToolResponse,
},
+ CreateAgentSession: {
+ call: schemas.CreateAgentSession,
+ response: schemas.DispatchedCodingAgent,
+ },
CreateBookingLink: {
call: schemas.CreateBookingLink,
response: schemas.BookingLinkResult,
@@ -813,6 +837,10 @@ const toolParserMap = {
response: schemas.ListTeamMembersResponse,
},
LoadTools: { call: schemas.LoadTools, response: schemas.LoadToolsResponse },
+ ManageAgentSession: {
+ call: schemas.ManageAgentSession,
+ response: schemas.SessionActionResult,
+ },
ManageBotChannelAccess: {
call: schemas.ManageBotChannelAccess,
response: schemas.ManageBotChannelAccessResponse,
@@ -861,6 +889,14 @@ const toolParserMap = {
call: schemas.ReadActivity,
response: schemas.ReadActivityResponse,
},
+ ReadAgentSession: {
+ call: schemas.ReadAgentSession,
+ response: schemas.SessionConversation,
+ },
+ ReadAgentSessionSharing: {
+ call: schemas.ReadAgentSessionSharing,
+ response: schemas.SessionSharingResponse,
+ },
ReadBookingSettings: {
call: schemas.ReadBookingSettings,
response: schemas.BookingSettingsResult,
@@ -1008,6 +1044,10 @@ const toolParserMap = {
call: schemas.TextEditorCodeExecution,
response: schemas.TextEditorCodeExecutionResponse,
},
+ UpdateAgentSessionSharing: {
+ call: schemas.UpdateAgentSessionSharing,
+ response: schemas.SessionSharingResponse,
+ },
UpdateBookingSettings: {
call: schemas.UpdateBookingSettings,
response: schemas.BookingSettingsResult,
@@ -1091,6 +1131,10 @@ type ToolDataMap = {
call: types.ContentSearch;
response: types.SearchToolResponse;
};
+ CreateAgentSession: {
+ call: types.CreateAgentSession;
+ response: types.DispatchedCodingAgent;
+ };
CreateBookingLink: {
call: types.CreateBookingLink;
response: types.BookingLinkResult;
@@ -1343,6 +1387,10 @@ type ToolDataMap = {
response: types.ListTeamMembersResponse;
};
LoadTools: { call: types.LoadTools; response: types.LoadToolsResponse };
+ ManageAgentSession: {
+ call: types.ManageAgentSession;
+ response: types.SessionActionResult;
+ };
ManageBotChannelAccess: {
call: types.ManageBotChannelAccess;
response: types.ManageBotChannelAccessResponse;
@@ -1385,6 +1433,14 @@ type ToolDataMap = {
call: types.ReadActivity;
response: types.ReadActivityResponse;
};
+ ReadAgentSession: {
+ call: types.ReadAgentSession;
+ response: types.SessionConversation;
+ };
+ ReadAgentSessionSharing: {
+ call: types.ReadAgentSessionSharing;
+ response: types.SessionSharingResponse;
+ };
ReadBookingSettings: {
call: types.ReadBookingSettings;
response: types.BookingSettingsResult;
@@ -1511,6 +1567,10 @@ type ToolDataMap = {
call: types.TextEditorCodeExecution;
response: types.TextEditorCodeExecutionResponse;
};
+ UpdateAgentSessionSharing: {
+ call: types.UpdateAgentSessionSharing;
+ response: types.SessionSharingResponse;
+ };
UpdateBookingSettings: {
call: types.UpdateBookingSettings;
response: types.BookingSettingsResult;
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
index c13e355f77..8981718657 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
@@ -38,12 +38,12 @@ export type ToolPropertyTargetEntityType =
| 'document'
| 'initiative'
| 'project'
- | 'chat'
| 'thread'
| 'channel'
| 'call'
| 'user'
- | 'company';
+ | 'company'
+ | 'chat';
/**
* Structured output from a deterministic workbook operation.
*/
@@ -249,15 +249,18 @@ export type BotOwnerSummary =
* offered to the model.
*/
export type SearchMatchType = 'partial' | 'exact';
-export type UnifiedSearchIndex =
+/**
+ * Searchable entities exposed to agents. Legacy conversations are not tool targets.
+ */
+export type SearchEntityType =
| 'agent_sessions'
| 'documents'
- | 'chats'
| 'emails'
| 'channels'
| 'projects'
| 'call_records'
- | 'calendar_events';
+ | 'calendar_events'
+ | 'chats';
/**
* Which tag set a tag belongs to, relative to the caller.
*/
@@ -269,19 +272,16 @@ export type TagMatch = 'any' | 'all';
/**
* A search result annotated with the caller-visible tags on the item.
*/
-export type TaggedSearchResult = {
+export type TaggedSessionAwareSearchResult = {
/**
* Tags on this item visible to the user.
*/
tags?: AppliedTag[];
-} & TaggedSearchResult1;
-export type TaggedSearchResult1 =
+} & TaggedSessionAwareSearchResult1;
+export type TaggedSessionAwareSearchResult1 =
| (DocumentSearchResponseItemWithMetadata & {
type: 'document';
})
- | (ChatSearchResponseItemWithMetadata & {
- type: 'chat';
- })
| (EmailSearchResponseItemWithMetadata & {
type: 'email';
})
@@ -795,6 +795,37 @@ export type BookingEventTypeId = string;
* The supported meaning of qualification at the booking step.
*/
export type Qualification = 'advisory' | 'required';
+export type SessionAwareSearchResult =
+ | (DocumentSearchResponseItemWithMetadata & {
+ type: 'document';
+ })
+ | (ChatSearchResponseItemWithMetadata & {
+ type: 'chat';
+ })
+ | (EmailSearchResponseItemWithMetadata & {
+ type: 'email';
+ })
+ | (ChannelMessageSearchResponseItem & {
+ type: 'channelMessage';
+ })
+ | (ChannelNameSearchResponseItem & {
+ type: 'channel';
+ })
+ | (ProjectSearchResponseItemWithMetadata & {
+ type: 'project';
+ })
+ | (CallRecordSearchResponseItemWithMetadata & {
+ type: 'call';
+ })
+ | (CrmCompanySearchResponseItem & {
+ type: 'company';
+ })
+ | (CalendarEventSearchResponseItemWithMetadata & {
+ type: 'calendarEvent';
+ })
+ | (AgentSessionSearchResponseItem & {
+ type: 'agentSession';
+ });
/**
* Outcome describes actual completion, including uncertain interrupted work.
*/
@@ -3577,13 +3608,14 @@ export type ConferenceProvider = 'microsoft_teams' | 'google_meet' | 'other';
export type ItemType =
| 'calendar_event'
| 'document'
- | 'ai_chat'
+ | 'agent_session'
| 'project'
| 'email'
| 'channel'
| 'channel_thread'
| 'call'
- | 'foreign_entity';
+ | 'foreign_entity'
+ | 'ai_chat';
/**
* Sort order for the list entities AI tool.
*/
@@ -3659,18 +3691,38 @@ export type EntityItem =
}
| {
/**
- * Chat id.
+ * Session id for ReadAgentSession and session actions.
*/
id: string;
/**
- * Chat name.
+ * Session title.
*/
name: string;
/**
- * Tags on the chat visible to the user.
+ * Owner's principal id.
*/
- tags?: AppliedTag[];
- type: 'aiChat';
+ ownerId: string;
+ /**
+ * Agent persona id.
+ */
+ botId: string;
+ /**
+ * Whether the session is archived.
+ */
+ isArchived: boolean;
+ /**
+ * Runtime connection status.
+ */
+ status: string;
+ /**
+ * Latest turn state, when available.
+ */
+ turnState?: string | null;
+ /**
+ * Selected repository, when present.
+ */
+ repoUrl?: string | null;
+ type: 'agentSession';
}
| {
/**
@@ -3783,6 +3835,12 @@ export type EntityItem =
[k: string]: unknown;
};
type: 'foreignEntity';
+ }
+ | {
+ type: 'aiChat';
+ id: string;
+ name: string;
+ tags?: AppliedTag[];
};
/**
* The caller's level on a form: view responds, edit changes questions and
@@ -3794,21 +3852,21 @@ export type FormAccess = 'view' | 'edit' | 'owner';
*/
export type NotificationState = 'unseen' | 'seen' | 'done';
/**
- * User-facing notification categories used for list filtering.
+ * Notification categories available to agents.
*/
-export type NotificationCategory =
+export type ToolNotificationCategory =
| 'email'
| 'message'
| 'channel'
| 'document'
| 'project'
- | 'chat'
| 'call'
| 'task'
| 'github'
| 'reminder'
| 'calendar'
- | 'agent';
+ | 'agent'
+ | 'chat';
/**
* Canonical entity types accepted by the notification-listing tool.
*
@@ -3816,8 +3874,8 @@ export type NotificationCategory =
* depend on `schemars`, while AI tool inputs require [`JsonSchema`].
*/
export type NotificationEntityType =
+ | 'agent_session'
| 'user'
- | 'chat'
| 'channel'
| 'channel_message'
| 'document'
@@ -3832,7 +3890,43 @@ export type NotificationEntityType =
| 'crm_contact'
| 'reminder'
| 'skill'
- | 'scheduled_action';
+ | 'scheduled_action'
+ | 'chat';
+/**
+ * Session lifecycle actions available to agents. Human approvals are deliberately absent.
+ */
+export type SessionAction =
+ | {
+ /**
+ * New display name.
+ */
+ name: string;
+ type: 'rename';
+ }
+ | {
+ /**
+ * Whether the session should be archived.
+ */
+ archived: boolean;
+ type: 'archive';
+ }
+ | {
+ type: 'delete';
+ }
+ | {
+ /**
+ * Self-contained message to the agent.
+ */
+ prompt: string;
+ type: 'prompt';
+ }
+ | {
+ type: 'stop';
+ };
+/**
+ * Delivery state of an accepted control.
+ */
+export type SessionControlStatus = 'sent' | 'queued';
/**
* Channel-access change to apply to a bot.
*/
@@ -3844,11 +3938,11 @@ export type ParticipantAction = 'add' | 'remove';
/**
* The kind of entity to move.
*/
-export type MoveableEntityType = 'document' | 'chat' | 'email' | 'project';
+export type MoveableEntityType = 'document' | 'email' | 'project' | 'chat';
/**
* The kind of item to move to the trash.
*/
-export type TrashableEntityType = 'document' | 'chat' | 'project';
+export type TrashableEntityType = 'document' | 'project' | 'chat';
/**
* What to do with an item's notifications.
*/
@@ -4110,6 +4204,18 @@ export type ToolActivityAction =
};
type: 'unknown';
};
+/**
+ * The two sides of a session conversation.
+ */
+export type SessionMessageRole = 'user' | 'agent';
+/**
+ * Who an item's share link admits.
+ */
+export type SessionLinkScope = 'off' | 'public' | 'team';
+/**
+ * Ordered from least to most access top -> bottom
+ */
+export type AccessLevel = 'view' | 'comment' | 'edit' | 'owner';
/**
* Position of a channel message.
*/
@@ -4368,14 +4474,10 @@ export type DocumentContentLocation =
| 'docx_bom_parts'
| 'converted_pdf'
| 'unknown';
-/**
- * Ordered from least to most access top -> bottom
- */
-export type AccessLevel = 'view' | 'comment' | 'edit' | 'owner';
/**
* The kind of an item inside a project.
*/
-export type ProjectItemType = 'document' | 'chat' | 'project';
+export type ProjectItemType = 'document' | 'project' | 'chat';
/**
* The kind of item to rename.
*/
@@ -4481,25 +4583,25 @@ export type ToolEntityType =
| 'task'
| 'initiative'
| 'project'
- | 'chat'
| 'thread'
| 'channel'
| 'call'
| 'user'
| 'company'
- | 'contact';
+ | 'contact'
+ | 'chat';
/**
* The kinds of item a user can favorite.
*/
export type FavoritableEntityType =
| 'document'
| 'project'
- | 'chat'
| 'channel'
| 'email'
| 'call'
| 'crm_company'
- | 'crm_contact';
+ | 'crm_contact'
+ | 'chat';
/**
* An explicit channel grant delta; omitted channels stay unchanged.
*/
@@ -4536,13 +4638,13 @@ export type ToolSenderPolicy = 'signal' | 'noise' | 'block';
export type ChannelShareEntityType =
| 'calendar_event'
| 'document'
- | 'chat'
| 'project'
| 'database'
| 'form'
| 'call'
| 'thread'
- | 'agent_session';
+ | 'agent_session'
+ | 'chat';
/**
* Content of a text editor code execution response - either a result or an error
*/
@@ -4559,6 +4661,10 @@ export type TextEditorCodeExecutionContent =
| (TextEditorCodeExecutionToolError & {
type: 'text_editor_code_execution_tool_result_error';
});
+/**
+ * A share can be disabled or grant a non-owner permission.
+ */
+export type SessionShareAccess = 'off' | 'view' | 'comment' | 'edit';
/**
* How much of a recurring series an update applies to.
*/
@@ -4601,7 +4707,7 @@ export type RoutineChange =
/**
* The kind of item whose sharing changes.
*/
-export type SharingEntityType = 'document' | 'chat' | 'project';
+export type SharingEntityType = 'document' | 'project' | 'chat';
/**
* Who an item's share link admits.
*/
@@ -5674,18 +5780,18 @@ export interface ConfigureBotResponse {
summary: string;
}
/**
- * Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; chat messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For chats, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
+ * Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; agent session messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For agent sessions, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
*/
export interface ContentSearch {
/**
- * The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For chats/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix.
+ * The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For sessions/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix.
*/
query: string;
matchType?: SearchMatchType & string;
/**
* Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. Projects and calendar events carry no indexed content, so they never match here — search those by name with NameSearch instead.
*/
- entityTypes?: UnifiedSearchIndex[];
+ entityTypes?: SearchEntityType[];
/**
* Search only the transcripts of these agent sessions, by id, and nothing else. Use it with your own session id to find the exact words of something said earlier in your conversation, including parts that were summarized to keep it within your context. Omit to search every type.
*/
@@ -5695,7 +5801,7 @@ export interface ContentSearch {
*/
inbox?: string | null;
/**
- * Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records) can match, so channels are dropped while a tag filter is active.
+ * Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, projects, call records) can match, so channels are dropped while a tag filter is active.
*/
tags?: TagFilter[] | null;
tagsMatch?: TagMatch;
@@ -5714,7 +5820,7 @@ export interface TagFilter {
scope?: TagScope | null;
}
export interface SearchToolResponse {
- results: TaggedSearchResult[];
+ results: TaggedSessionAwareSearchResult[];
}
/**
* A tag applied to an item, resolved to its human-readable label.
@@ -5827,68 +5933,6 @@ export interface SearchHighlight {
*/
bcc?: string[];
}
-/**
- * ChatSearchResponse object with channel metadata we fetch from macrodb. we don't store these
- * timestamps in opensearch as they would require us to update each chat message record for the chat
- * every time the chat updates (specifically for updated_at and viewed_at)
- */
-export interface ChatSearchResponseItemWithMetadata {
- /**
- * Metadata from the database. None if the chat doesn't exist in the database.
- */
- metadata?: ChatMetadata | null;
- /**
- * Standardized fields that all item types will share.
- * These field names are being aligned across all item types
- * for consistency in our data model.
- */
- id: string;
- name: string;
- owner_id: string;
- /**
- * The id of the chat
- */
- chat_id: string;
- /**
- * The id of the creator of the chat
- */
- user_id: string;
- /**
- * The search results for the chat
- * This may be empty if the search result match was on the chat title only
- */
- chat_search_results: ChatMessageSearchResult[];
-}
-/**
- * Metadata for a chat fetched from the database
- */
-export interface ChatMetadata {
- created_at: string;
- updated_at: string;
- viewed_at?: string | null;
- project_id?: string | null;
- deleted_at?: string | null;
-}
-/**
- * A chat match for a given message id
- */
-export interface ChatMessageSearchResult {
- /**
- * The chat message id for the chat
- * This is only present if the search match was on the chat message content
- */
- chat_message_id?: string | null;
- /**
- * The role of the chat message
- * This is only present if the search match was on the chat message content
- */
- role?: string | null;
- highlight: SearchHighlight;
- /**
- * The score of the result
- */
- score?: number | null;
-}
/**
* EmailSearchResponseItem object with email metadata we fetch from email service. we don't store these
* timestamps in opensearch as they would require us to update each email message record for the thread
@@ -6379,6 +6423,36 @@ export interface SearchGotoAgentSession {
message_turn: number;
author: AgentSessionAuthor;
}
+/**
+ * Start a new session with a coding or chat agent from ListAgents. Provide the agent botId and a self-contained initial prompt. The new session does not inherit this conversation. Returns its session ID after the first prompt is accepted, not completed work. Use ManageAgentSession to continue an existing session. Create once; do not automatically retry after an uncertain failure.
+ */
+export interface CreateAgentSession {
+ /**
+ * Agent persona botId from ListAgents.
+ */
+ agentId: string;
+ /**
+ * Complete initial task and relevant context.
+ */
+ prompt: string;
+}
+/**
+ * A newly opened session whose first prompt has been accepted.
+ */
+export interface DispatchedCodingAgent {
+ /**
+ * Session to show in a magic chip.
+ */
+ agent_session_id: string;
+ /**
+ * Persona that owns the session's identity.
+ */
+ agent_id: string;
+ /**
+ * Persona display name.
+ */
+ agent_name: string;
+}
/**
* Create a reusable booking page, not a calendar meeting. First use ListBookingLinks to discover a suitable existing link or reuse availability. Supply a full draft with all seven weekdays (Sunday=0), IANA time zone, and real host IDs; personal links use the authenticated user and individual mode. For a team use a real team ID and collective or roundRobin mode. Set enabled only when the user wants to accept bookings. No invitations are sent by creating a link. Repeating an identical draft with the same slug reuses the saved link; a different draft at that slug conflicts. Create or edit booking links only after conversational confirmation, with no review card or interactive form. First explain all proposed details clearly in your reply: personal or team ownership, named hosts and who attends, meeting name, description, duration, location, Macro call, or Google Meet, time zone, weekly hours and date exceptions, link name, buffers, minimum notice, booking window, slot interval, daily limit, guest questions and whether bookings are enabled. Ask whether to proceed and stop. Only in a later turn after the user approves that specific proposal, call this tool with their approving reply quoted verbatim in userConfirmation. The original request is not confirmation; never invent or paraphrase approval. Never ask the user for teamId, host IDs, schedule IDs, revisions or JSON: discover IDs with ListBookingLinks and ListTeamMembers. Default to personal ownership unless a team is requested, and clarify ambiguous choices by name. After execution, share the saved URL with an <m-booking-link-mention> chip (profileId/slug/url from the result), not a bare URL. Returns actual saved IDs, revision, full draft and shareable URL. Manual approval must be false; guest booking requires a connected, synced writable calendar. For video, set macroCall (preferred) or googleMeet, never both. Booking a macroCall link creates the call and attaches its join link to the invitation.
*/
@@ -7157,10 +7231,67 @@ export interface BookingTarget {
profileId: BookingProfileId;
eventTypeId: BookingEventTypeId;
}
-export interface MessageWithAttachments {
- content: string;
- date: string;
- attachmentIds: string[];
+/**
+ * ChatSearchResponse object with channel metadata we fetch from macrodb. we don't store these
+ * timestamps in opensearch as they would require us to update each chat message record for the chat
+ * every time the chat updates (specifically for updated_at and viewed_at)
+ */
+export interface ChatSearchResponseItemWithMetadata {
+ /**
+ * Metadata from the database. None if the chat doesn't exist in the database.
+ */
+ metadata?: ChatMetadata | null;
+ /**
+ * Standardized fields that all item types will share.
+ * These field names are being aligned across all item types
+ * for consistency in our data model.
+ */
+ id: string;
+ name: string;
+ owner_id: string;
+ /**
+ * The id of the chat
+ */
+ chat_id: string;
+ /**
+ * The id of the creator of the chat
+ */
+ user_id: string;
+ /**
+ * The search results for the chat
+ * This may be empty if the search result match was on the chat title only
+ */
+ chat_search_results: ChatMessageSearchResult[];
+}
+/**
+ * Metadata for a chat fetched from the database
+ */
+export interface ChatMetadata {
+ created_at: string;
+ updated_at: string;
+ viewed_at?: string | null;
+ project_id?: string | null;
+ deleted_at?: string | null;
+}
+/**
+ * A chat match for a given message id
+ */
+export interface ChatMessageSearchResult {
+ /**
+ * The chat message id for the chat
+ * This is only present if the search match was on the chat message content
+ */
+ chat_message_id?: string | null;
+ /**
+ * The role of the chat message
+ * This is only present if the search match was on the chat message content
+ */
+ role?: string | null;
+ highlight: SearchHighlight;
+ /**
+ * The score of the result
+ */
+ score?: number | null;
}
/**
* Every mutation reports its result; no execution history is retained.
@@ -7680,7 +7811,7 @@ export interface ToolField {
readOnly: boolean;
}
/**
- * Create a project — shown as a folder in the app UI. Documents, AI chats, email threads, and other projects can be placed inside it.
+ * Create a project — shown as a folder in the app UI. Documents, email threads, and other projects can be placed inside it.
*/
export interface CreateProject {
/**
@@ -7786,7 +7917,7 @@ export interface CreateSkillResponse {
documentId: string;
}
/**
- * Create a new tag — a colored label the user can apply to documents, emails, tasks, AI chats, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead.
+ * Create a new tag — a colored label the user can apply to documents, emails, tasks, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead.
*/
export interface CreateTag {
/**
@@ -8318,23 +8449,6 @@ export interface DispatchCodingAgent {
*/
prompt: string;
}
-/**
- * A newly opened session whose first prompt has been accepted.
- */
-export interface DispatchedCodingAgent {
- /**
- * Session to show in a magic chip.
- */
- agent_session_id: string;
- /**
- * Persona that owns the session's identity.
- */
- agent_id: string;
- /**
- * Persona display name.
- */
- agent_name: string;
-}
/**
* Present results to the user as a rich view. The `view` argument is a dynamic-UI view object (a title plus an ordered list of widgets) following the dynamic-UI schema provided to you. The view is rendered immediately in the chat; this tool returns as soon as it is dispatched.
*/
@@ -8350,7 +8464,7 @@ export interface DisplayResultsResponse {
message: string;
}
/**
- * Make a copy of a document (including a task) or an AI chat, owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id.
+ * Make a copy of a document (including a task), owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id.
*/
export interface DuplicateItem {
entityType: DuplicableEntityType;
@@ -8359,7 +8473,7 @@ export interface DuplicateItem {
*/
entityId: string;
/**
- * Name for the copy of a document. Omit to use "<original name> copy". AI chat copies always keep the original name.
+ * Name for the copy of a document. Omit to use "<original name> copy".
*/
name?: string | null;
}
@@ -10993,7 +11107,7 @@ export interface ToolTableSummary {
sqlName: string;
}
/**
- * Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as "what happened today", "what's going on", "catch me up", or "what happened in standup today"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as "list my tasks", "tasks assigned to me", or "tasks I completed yesterday", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {"l":{"dst":"task"}} and includeTypes ["document"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For "completed yesterday", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. "my items tagged bug-report"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
+ * Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, agent sessions, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as "what happened today", "what's going on", "catch me up", or "what happened in standup today"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as "list my tasks", "tasks assigned to me", or "tasks I completed yesterday", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {"l":{"dst":"task"}} and includeTypes ["document"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For "completed yesterday", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. "my items tagged bug-report"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
*/
export interface ListEntities {
/**
@@ -11018,9 +11132,9 @@ export interface ListEntities {
[k: string]: unknown;
};
/**
- * Full soup AST AI chat filter (cf).
+ * Agent-session filter (asf): use {"l":{"id":"<session UUID>"}} for a session, or {"l":{"o":"macro|[email protected]"}} for an owner.
*/
- cf?: {
+ asf?: {
[k: string]: unknown;
};
/**
@@ -11074,7 +11188,7 @@ export interface ListEntities {
*/
inbox?: string | null;
/**
- * Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, AI chats, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags.
+ * Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags.
*/
tags?: TagFilter[] | null;
tagsMatch?: TagMatch;
@@ -11391,7 +11505,7 @@ export interface ListNotifications {
/**
* Filter to specific notification item types. If omitted, returns all types. Example: ["email", "message"] returns only email and message notifications.
*/
- includeTypes?: NotificationCategory[] | null;
+ includeTypes?: ToolNotificationCategory[] | null;
/**
* Filter to notifications for specific entities. Pair each id with its canonical entityType to avoid ambiguity. Example: [{"entityType":"email_thread","id":"..."}] returns notifications for one email thread.
*/
@@ -11661,6 +11775,37 @@ export interface ToolMatch {
*/
description: string;
}
+/**
+ * Rename, archive/unarchive, delete, prompt, or stop an agent session. Use ListEntities or NameSearch to find sessions and ReadAgentSession to inspect them. Rename, archive, and delete require ownership; prompting and stopping require edit access. Delete releases the runtime and permanently removes the session; use only when the user asks to delete it. Prompt returns sent/queued acceptance, not completed work. After an uncertain error, read the session before retrying; never automatically resend a prompt. This tool cannot answer permission or approval requests.
+ */
+export interface ManageAgentSession {
+ /**
+ * Session UUID from a mention, listing, or search result.
+ */
+ sessionId: string;
+ action: SessionAction;
+}
+/**
+ * A safely attributable action result.
+ */
+export interface SessionActionResult {
+ /**
+ * Session acted on.
+ */
+ sessionId: string;
+ /**
+ * Human-readable outcome.
+ */
+ message: string;
+ /**
+ * Accepted prompt or stop id, when applicable.
+ */
+ actionId?: string | null;
+ /**
+ * Whether a control was sent or queued.
+ */
+ status?: SessionControlStatus | null;
+}
/**
* Grant or revoke a manageable bot's access to one channel. Granting requires the current user to be a channel member. Both actions require the user to own the bot or belong to its owning team; revoking still works after the manager leaves the channel. Granting access creates that channel's webhook URL; revoking access disables posting to that channel. Use only after the user asks to change bot access.
*/
@@ -11761,7 +11906,7 @@ export interface MarkNotificationsSeen {
notificationIds: string[];
}
/**
- * Move a document, AI chat, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving an AI chat or a project requires owning it.
+ * Move a document, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving a project requires owning it.
*/
export interface MoveToProject {
entityType: MoveableEntityType;
@@ -11788,7 +11933,7 @@ export interface MoveToProjectResponse {
message: string;
}
/**
- * Delete a document (including a task), an AI chat, or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool.
+ * Delete a document (including a task), or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool.
*/
export interface MoveToTrash {
entityType: TrashableEntityType;
@@ -11841,7 +11986,7 @@ export interface MuteNotificationsResponse {
snoozeUntil?: string | null;
}
/**
- * Search items by their name or title: document name, email subject, chat title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
+ * Search items by their name or title: document name, email subject, agent session title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like "what happened today", "what's going on", "catch me up", or "what happened in standup today"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).
*/
export interface NameSearch {
/**
@@ -11852,13 +11997,13 @@ export interface NameSearch {
/**
* Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records'].
*/
- entityTypes?: UnifiedSearchIndex[];
+ entityTypes?: SearchEntityType[];
/**
* Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results.
*/
inbox?: string | null;
/**
- * Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, AI chats, projects, call records, calendar events) can match, so channels are dropped while a tag filter is active.
+ * Restrict results to items carrying the given tags — any of them by default, every one of them with tagsMatch="all". Each entry names a tag by its label, matched case-insensitively against the user's own tags; only set scope ("personal" or "team") when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, emails, projects, call records, calendar events) can match, so channels are dropped while a tag filter is active.
*/
tags?: TagFilter[] | null;
tagsMatch?: TagMatch;
@@ -12164,6 +12309,131 @@ export interface ToolActivityEvent {
*/
occurredAt: string;
}
+/**
+ * Read an agent session by its ID from an agent-session mention or search result. Returns the latest 20 messages in chronological order, including prompts, replies, tool activity and errors. Optionally select a turn number to inspect earlier history. Each message is capped at 4000 characters; truncated flags identify omitted history or text. Requires view access to the session.
+ */
+export interface ReadAgentSession {
+ /**
+ * The agent session UUID from its mention or search result.
+ */
+ sessionId: string;
+ /**
+ * Read only this turn number, as returned in messages; omit for recent history.
+ */
+ turn?: number | null;
+}
+/**
+ * A readable session conversation, including tool activity and failures.
+ */
+export interface SessionConversation {
+ /**
+ * Session identity.
+ */
+ sessionId: string;
+ /**
+ * User-facing session name.
+ */
+ name: string;
+ /**
+ * Owner's principal id.
+ */
+ ownerId: string;
+ /**
+ * Agent persona id.
+ */
+ botId: string;
+ /**
+ * Whether the session is archived and read-only.
+ */
+ isArchived: boolean;
+ /**
+ * Configured runtime.
+ */
+ harness: string;
+ /**
+ * Selected model.
+ */
+ model: string;
+ /**
+ * Last runtime status.
+ */
+ status: string;
+ /**
+ * Messages in the requested turn, or the latest messages, oldest first.
+ */
+ messages: SessionConversationMessage[];
+ /**
+ * Number of messages matching the requested turn before bounding.
+ */
+ totalMessages: number;
+ /**
+ * Whether older messages or text were omitted.
+ */
+ truncated: boolean;
+}
+/**
+ * One folded prompt or reply.
+ */
+export interface SessionConversationMessage {
+ /**
+ * Turn number; pass it back to read that turn specifically.
+ */
+ turn: number;
+ role: SessionMessageRole;
+ /**
+ * Readable prose, tool activity, outputs, and errors.
+ */
+ content: string;
+ /**
+ * Terminal runtime error, retained separately even when earlier text is truncated.
+ */
+ failure?: string | null;
+ /**
+ * Whether this message's text exceeded the character budget.
+ */
+ truncated: boolean;
+}
+/**
+ * Read an agent session's current owner, link sharing, team access, and channel grants. Requires view access. Use UpdateAgentSessionSharing to change grants as the owner.
+ */
+export interface ReadAgentSessionSharing {
+ /**
+ * Session UUID.
+ */
+ sessionId: string;
+}
+/**
+ * Authoritative sharing settings after a read or mutation.
+ */
+export interface SessionSharingResponse {
+ /**
+ * Session owner's principal.
+ */
+ owner: string;
+ linkScope: SessionLinkScope;
+ /**
+ * Access through the enabled link.
+ */
+ linkAccess?: AccessLevel | null;
+ /**
+ * Explicit access for the owner's team.
+ */
+ teamAccess?: AccessLevel | null;
+ /**
+ * Explicit channel grants.
+ */
+ channels: SessionChannelGrant[];
+}
+/**
+ * A channel's existing session access.
+ */
+export interface SessionChannelGrant {
+ /**
+ * Channel identity.
+ */
+ channelId: string;
+ access: AccessLevel;
+}
/**
* Read the full personal or team Booking Links configuration: booking-page name and introduction, reusable schedules, default availability, and all link settings with IDs and revision. Omit teamId for personal. Discover team IDs using ListBookingLinks. This read does not create a profile. Use the returned profile with UpdateBookingSettings to change shared availability or page settings.
*/
@@ -12850,49 +13120,6 @@ export interface ReadChannelThreadInfo {
*/
latestReplyAt?: string | null;
}
-/**
- * Retrieve a chat thread's message history by its ID. Returns the conversation title and messages with their roles, content, and attachment references.
- */
-export interface ReadChat {
- /**
- * The id of the chat thread to read.
- */
- chatId: string;
-}
-/**
- * Response for [`ReadChat`].
- */
-export interface ReadChatResponse {
- /**
- * The chat id.
- */
- chatId: string;
- /**
- * The chat title.
- */
- title: string;
- /**
- * The messages in the chat.
- */
- messages: ChatMessagePreview[];
-}
-/**
- * A single message in the tool response.
- */
-export interface ChatMessagePreview {
- /**
- * The role of the message author (user, assistant, or system).
- */
- role: string;
- /**
- * The text content of the message.
- */
- content: string;
- /**
- * IDs of attachments referenced by this message.
- */
- attachmentIds: string[];
-}
/**
* Retrieve a document's content and its comment threads, including inline comments with the text they are on, Discussion comments, replies and resolved state.
*/
@@ -13368,7 +13595,7 @@ export interface ReadPresentationResponse {
content: string;
}
/**
- * List the direct contents of a project (shown as a folder in the app UI): its documents, AI chats, and nested projects. Requires view access to the project. Email threads filed into the project are not included.
+ * List the direct contents of a project (shown as a folder in the app UI): its documents and nested projects. Requires view access to the project. Email threads filed into the project are not included.
*/
export interface ReadProject {
/**
@@ -13601,7 +13828,7 @@ export interface RenameDocumentResponse {
message: string;
}
/**
- * Rename a project (shown as a folder in the app) or an AI chat. Renaming a project requires edit access; renaming an AI chat requires owning it. Use RenameDocument for documents and tasks, and RenameChannel for channels.
+ * Rename a project (shown as a folder in the app). Renaming a project requires edit access. Use RenameDocument for documents and tasks, and RenameChannel for channels.
*/
export interface RenameItem {
entityType: RenameableEntityType;
@@ -14284,7 +14511,7 @@ export interface SetSenderPolicyResponse {
summary: string;
}
/**
- * Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, chat, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists.
+ * Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists.
*/
export interface ShareWithChannel {
/**
@@ -14399,6 +14626,41 @@ export interface TextEditorCodeExecutionResult {
export interface TextEditorCodeExecutionToolError {
error_code: CodeExecutionErrorCode;
}
+/**
+ * Change an agent session's link, team, or channel sharing as its owner. Omitted settings remain unchanged; off revokes that grant. Requires an explicit user request to change sharing. Private persona conversations cannot be shared. Returns the resulting settings.
+ */
+export interface UpdateAgentSessionSharing {
+ /**
+ * Session UUID.
+ */
+ sessionId: string;
+ /**
+ * Who the item's share link admits: public (anyone with the link), team (the owner's team members with the link), or off to disable link sharing.
+ */
+ linkScope?: SessionLinkScope | null;
+ /**
+ * Permission granted by an enabled share link. Off resets it to the default level.
+ */
+ linkAccess?: SessionShareAccess | null;
+ /**
+ * Access for everyone on the owner's team; off removes it.
+ */
+ teamAccess?: SessionShareAccess | null;
+ /**
+ * Individual channel grants to set or remove; other channel grants stay unchanged.
+ */
+ channels?: SessionSharingChannel[] | null;
+}
+/**
+ * One channel's grant to set or remove.
+ */
+export interface SessionSharingChannel {
+ /**
+ * Channel id to share with or revoke.
+ */
+ channelId: string;
+ access: SessionShareAccess;
+}
/**
* Update Booking Links settings after reading ReadBookingSettings. Pass the full profile with its current revision, preserving fields the user did not request changing. Supports booking-page name and introduction; adding, editing and deleting reusable schedules and date overrides; changing defaultScheduleId; reassigning link schedules; duplicating, deleting, enabling or pausing links. Generate new UUIDs for new schedules, links and questions; preserve existing IDs. Changing a shared schedule affects every link referencing it and personal default hours affect team hosting. Deleting a link does not cancel existing bookings. Explain affected links before changing shared hours or deleting. A stale revision fails: re-read and reconcile rather than overwriting. Use CreateBookingLink or EditBookingLink for ordinary single-link authoring and their conversational confirmation contract. Any team member can edit team settings. Before saving, explain the proposed changes and their personal/team scope, ask whether to proceed, and wait for the user's approving reply in a later turn. Quote that reply verbatim in userConfirmation. Do not use the original request as confirmation.
*/
@@ -14656,7 +14918,7 @@ export interface UpdateRoutine {
change: RoutineChange;
}
/**
- * Change who can access a document (including a task), an AI chat, or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning an AI chat or project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives).
+ * Change who can access a document (including a task), or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning a project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives).
*/
export interface UpdateSharing {
entityType: SharingEntityType;
@@ -14970,6 +15232,49 @@ export interface ExecutionReceipt {
*/
error?: string | null;
}
+/**
+ * Retrieve a chat thread's message history by its ID. Returns the conversation title and messages with their roles, content, and attachment references.
+ */
+export interface ReadChat {
+ /**
+ * The id of the chat thread to read.
+ */
+ chatId: string;
+}
+/**
+ * Response for [`ReadChat`].
+ */
+export interface ReadChatResponse {
+ /**
+ * The chat id.
+ */
+ chatId: string;
+ /**
+ * The chat title.
+ */
+ title: string;
+ /**
+ * The messages in the chat.
+ */
+ messages: ChatMessagePreview[];
+}
+/**
+ * A single message in the tool response.
+ */
+export interface ChatMessagePreview {
+ /**
+ * The role of the message author (user, assistant, or system).
+ */
+ role: string;
+ /**
+ * The text content of the message.
+ */
+ content: string;
+ /**
+ * IDs of attachments referenced by this message.
+ */
+ attachmentIds: string[];
+}
/**
* Read threaded content by ID(s). Supports reading channels, chats, and projects by their respective IDs. Use this tool when you need to retrieve the full content of a specific item(s). For documents, use ReadContent or ReadMetadata instead.
* Channel transcripts only include the latest 150 messages. Use 'messages_since' to see messages in a different time window.
@@ -14993,3 +15298,8 @@ export interface ConversationRecord {
title: string;
messages: MessageWithAttachments[];
}
+export interface MessageWithAttachments {
+ content: string;
+ date: string;
+ attachmentIds: string[];
+}
diff --git a/crates/agent_code_mode/AGENTS.md b/crates/agent_code_mode/AGENTS.md
index 9ed84c44b7..28a0a372da 100644
--- a/crates/agent_code_mode/AGENTS.md
+++ b/crates/agent_code_mode/AGENTS.md
@@ -22,6 +22,10 @@ Inbound adapters authenticate and delegate to domain services. Outbound adapters
implement persistence; the harness composition root wires native actions and
session presentation. Never replay an uncertain submitted action.
+## Tool contracts
+
+- Keep native `NameSearch` and `ListEntities` available for session-aware discovery; agent SDK documentation excludes legacy chats and workspace feeds.
+
## Checks
- `cargo test -p agent_code_mode --lib` from the repository root, with live local
diff --git a/crates/agent_code_mode/SKILL.md b/crates/agent_code_mode/SKILL.md
index f4c2c7a242..6f5b3f8307 100644
--- a/crates/agent_code_mode/SKILL.md
+++ b/crates/agent_code_mode/SKILL.md
@@ -22,7 +22,7 @@ macro, session and execution are real SDK handles. You can instead import {Macro
## Useful workflows
-- For a workspace overview, run small per-category macro.workspace.page({includeTypes:[type], limit:3}) requests concurrently in one execution. Return compact metadata and each page.hasMore. A mixed page can be dominated by one category; a sample is not a category total. Exact workspace types include calendar_event, ai_chat and channel_thread. Tasks use includeTypes:["document"], df:{l:{dst:"task"}}. AST & and | are binary; a single filter stays a leaf.
+- For a workspace overview, use the direct ListEntities tool, including agent_session when the user asks about agent work. Use NameSearch for mixed-entity name searches and ContentSearch for session history. Return compact metadata and preserve pagination and source-scope limits. A sample is not a category total. Tasks use includeTypes:["document"], df:{l:{dst:"task"}}. AST & and | are binary; a single filter stays a leaf.
- Search several precise phrases concurrently, read relevant documents, then calculate an aggregate in one execution. Preserve query attribution, source IDs and sampling limits.
- Collect a bounded recent-email batch, fetch relevant content, then map macro.ai.decide over it with bounded parallelism. Retain every error and distinguish probability estimates from facts. The ai guide has a complete example.
- Generate structured extraction with macro.ai.structuredCompletion and toolset:{type:'none'}, using source text already fetched; check the returned outcome rather than assuming success.
diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.json
index d31a0d8e05..88d733e0f7 100644
--- a/crates/agent_code_mode/src/domain/documentation.json
+++ b/crates/agent_code_mode/src/domain/documentation.json
@@ -3,7 +3,7 @@
"name": "agentSessions",
"description": "Create and inspect agent sessions, saved code executions, and editable email or calendar review stacks.",
"overview": "<!-- src/entities/agent-sessions/agent-session/type-aliases/CreateManagedSessionOptions.md -->\n# Type Alias: CreateManagedSessionOptions\n\n> **CreateManagedSessionOptions** = \\{ `instructions?`: `string`; `model?`: `string`; `prompt?`: `string`; `repoBranch?`: `string`; `repoUrl?`: `string`; \\}\n\nWhat a managed session is created with.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-instructions\"></a> `instructions?` | `string` | Instructions the session's runtime works under, fixed for its life. |\n| <a id=\"property-model\"></a> `model?` | `string` | The model the session runs on, instead of its persona's. The session's model from creation, read back as [AgentSession.model](../classes/AgentSession.md#property-model). |\n| <a id=\"property-prompt\"></a> `prompt?` | `string` | First prompt to deliver once the session is running. |\n| <a id=\"property-repobranch\"></a> `repoBranch?` | `string` | The branch the session starts on; needs `repoUrl`. Omitted, the repository's default branch. |\n| <a id=\"property-repourl\"></a> `repoUrl?` | `string` | The repository the session works on, as one of the URLs [AgentSession.repositories](../classes/AgentSession.md#repositories) lists for the caller. Omitted, the runtime chooses from the prompt. Honored for Cursor sessions. |\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/SelectableRepository.md -->\n# Type Alias: SelectableRepository\n\n> **SelectableRepository** = \\{ `defaultBranch?`: `string`; `url`: `string`; \\}\n\nA GitHub repository the caller can point a managed session at.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-defaultbranch\"></a> `defaultBranch?` | `string` | The branch its clones check out, and where a session starts unless `createManaged` names another. Absent for a repository with no commits. |\n| <a id=\"property-url\"></a> `url` | `string` | The canonical `https://github.com/owner/name` URL, as `createManaged` takes it. |\n\n\n<!-- src/entities/agent-sessions/namespace/classes/AgentSessionNamespace.md -->\n# Class: AgentSessionNamespace\n\nEntry point for coding-agent sessions.\n\n## Constructors\n\n### Constructor\n\n> **new AgentSessionNamespace**(`client`): `AgentSessionNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`AgentSessionNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nA handle to an agent session by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### codingPreferences()\n\n> **codingPreferences**(): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nWhat the caller's new coding sessions are told to do beyond their assignment.\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### createManaged()\n\n> **createManaged**(`opts?`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\nCreate a managed agent session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`CreateManagedSessionOptions`](../../agent-session/type-aliases/CreateManagedSessionOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\n***\n\n### defaultSandboxSize()\n\n> **defaultSandboxSize**(): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nThe caller's default sandbox size for new `@coder` sessions.\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\nThe sessions linked to the GitHub pull request at `url` that the caller\ncan view.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\n***\n\n### repositories()\n\n> **repositories**(): `Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\nThe GitHub repositories the caller can hand a managed session, with the\nbranch each one's sessions start on by default.\n\n#### Returns\n\n`Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\n***\n\n### repositoryBranches()\n\n> **repositoryBranches**(`repoUrl`): `Promise`\\<`string`[]\\>\n\nBranch names on one repository the caller can start a managed session\nfrom. `repoUrl` is one of the URLs [AgentSessionNamespace.repositories](#repositories)\nlists.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `repoUrl` | `string` |\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### setCodingPreferences()\n\n> **setCodingPreferences**(`preferences`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nReplace the caller's coding preferences.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `preferences` | [`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md) |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### setDefaultSandboxSize()\n\n> **setDefaultSandboxSize**(`size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nSet the caller's default sandbox size for the next `@coder` mention.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n",
- "documentation": "# Macro SDK: agentSessions\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/agent-harness/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentAction.md -->\n# Type Alias: AgentAction\n\n> **AgentAction** = [`AgentPromptAction`](AgentPromptAction.md) & \\{ `type`: `\"prompt\"`; \\} \\| [`AgentSetModelAction`](AgentSetModelAction.md) & \\{ `type`: `\"setModel\"`; \\} \\| [`AgentSetConfigOptionAction`](AgentSetConfigOptionAction.md) & \\{ `type`: `\"setConfigOption\"`; \\} \\| \\{ `type`: `\"compact\"`; \\} \\| \\{ `type`: `\"stop\"`; \\} \\| [`AgentRespondElicitationAction`](AgentRespondElicitationAction.md) & \\{ `type`: `\"respondElicitation\"`; \\} \\| [`AgentPermissionAction`](AgentPermissionAction.md) & \\{ `type`: `\"respondToPermission\"`; \\}\n\nOne thing a caller wants an agent to do.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentActionId.md -->\n# Type Alias: AgentActionId\n\n> **AgentActionId** = `string`\n\nIdentifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationDto.md -->\n# Type Alias: AgentConversationDto\n\n> **AgentConversationDto** = \\{ `available`: `boolean`; `avatarUrl?`: `string` \\| `null`; `botId`: `string`; `channelId`: `string`; `name`: `string`; `sessions`: [`AgentConversationSessionDto`](AgentConversationSessionDto.md)[]; `settingsChanged`: `boolean`; `turns`: [`AgentConversationTurnDto`](AgentConversationTurnDto.md)[]; \\}\n\nAn agent's conversation in a channel, as the person it is with sees it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-available\"></a> `available` | `boolean` | Whether the caller may currently send a new prompt. |\n| <a id=\"property-avatarurl\"></a> `avatarUrl?` | `string` \\| `null` | Optional persona avatar. |\n| <a id=\"property-botid\"></a> `botId` | `string` | Persona id (without the bot principal prefix). |\n| <a id=\"property-channelid\"></a> `channelId` | `string` | The channel containing the visible transcript. |\n| <a id=\"property-name\"></a> `name` | `string` | Persona's historical display name. |\n| <a id=\"property-sessions\"></a> `sessions` | [`AgentConversationSessionDto`](AgentConversationSessionDto.md)[] | The sessions the conversation has run on, oldest first. |\n| <a id=\"property-settingschanged\"></a> `settingsChanged` | `boolean` | Whether new persona settings are available to adopt explicitly. |\n| <a id=\"property-turns\"></a> `turns` | [`AgentConversationTurnDto`](AgentConversationTurnDto.md)[] | Persistent state of each accepted message and its current attempt. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationSessionDto.md -->\n# Type Alias: AgentConversationSessionDto\n\n> **AgentConversationSessionDto** = \\{ `createdAt`: `string`; `isCurrent`: `boolean`; `sessionId`: `string`; \\}\n\nOne session a conversation has run on; every channel message stays visible.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the session began. |\n| <a id=\"property-iscurrent\"></a> `isCurrent` | `boolean` | Whether this is the current agent context. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Session whose controls and live events belong to this context. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationTurnDto.md -->\n# Type Alias: AgentConversationTurnDto\n\n> **AgentConversationTurnDto** = \\{ `actionId`: `string`; `createdAt`: `string`; `replyMessageId?`: `string` \\| `null`; `retryable`: `boolean`; `sessionId`: `string`; `sourceMessageId`: `string`; `state`: [`ConversationTurnState`](ConversationTurnState.md); \\}\n\nExecution status without exposing the persona prompt or stored credentials.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | `string` | Current runtime attempt identity. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the source message was first accepted. |\n| <a id=\"property-replymessageid\"></a> `replyMessageId?` | `string` \\| `null` | The associated agent reply, if it has been posted. |\n| <a id=\"property-retryable\"></a> `retryable` | `boolean` | Whether Retry would be accepted now. A failed attempt is not retryable until its reply says how it ended. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Session carrying this turn. |\n| <a id=\"property-sourcemessageid\"></a> `sourceMessageId` | `string` | The user's message in the channel timeline. |\n| <a id=\"property-state\"></a> `state` | [`ConversationTurnState`](ConversationTurnState.md) | Durable execution state. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentPermissionAction.md -->\n# Type Alias: AgentPermissionAction\n\n> **AgentPermissionAction** = \\{ `answer`: [`PermissionAnswer`](PermissionAnswer.md); `requestId`: `unknown`; \\}\n\nA user's answer to the agent's `session/request_permission`.\n\nUnlike every other action this is not a new request but the reply to one\nthe agent made, so it carries the agent's own request id rather than\nreceiving a server-minted one.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-answer\"></a> `answer` | [`PermissionAnswer`](PermissionAnswer.md) | What the user decided. |\n| <a id=\"property-requestid\"></a> `requestId` | `unknown` | The agent's JSON-RPC request id, echoed verbatim from the folded permission part. A string or a number on the wire; agents mint both, and `7` does not answer `\"7\"`. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentPromptAction.md -->\n# Type Alias: AgentPromptAction\n\n> **AgentPromptAction** = \\{ `attachments?`: [`PromptAttachment`](PromptAttachment.md)[]; `prompt`: `string`; \\}\n\nAsk the agent to work on something.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments?` | [`PromptAttachment`](PromptAttachment.md)[] | Files the prompt refers to, in the order the user attached them. Delivered after the text as one `resource_link` block each. |\n| <a id=\"property-prompt\"></a> `prompt` | `string` | What to tell the agent. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentRespondElicitationAction.md -->\n# Type Alias: AgentRespondElicitationAction\n\n> **AgentRespondElicitationAction** = [`ElicitationAnswer`](ElicitationAnswer.md) & \\{ `requestId`: [`ElicitationRequestId`](ElicitationRequestId.md); \\}\n\nAnswer an elicitation the agent is waiting on.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `requestId` | [`ElicitationRequestId`](ElicitationRequestId.md) | The agent's `elicitation/create` request id - not an [`AgentActionId`], because the agent minted it. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md -->\n# Type Alias: AgentSessionChangesResponse\n\n> **AgentSessionChangesResponse** = \\{ `attempt?`: `null` \\| [`CaptureAttemptDto`](CaptureAttemptDto.md); `capturing`: `boolean`; `changeset?`: `null` \\| [`ChangesetDto`](ChangesetDto.md); \\}\n\nResponse body for `GET /agent-sessions/{session_id}/changes`.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attempt\"></a> `attempt?` | `null` \\| [`CaptureAttemptDto`](CaptureAttemptDto.md) | - |\n| <a id=\"property-capturing\"></a> `capturing` | `boolean` | A capture is running right now. |\n| <a id=\"property-changeset\"></a> `changeset?` | `null` \\| [`ChangesetDto`](ChangesetDto.md) | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionLogEntryDto.md -->\n# Type Alias: AgentSessionLogEntryDto\n\n> **AgentSessionLogEntryDto** = [`LogFrameDto`](LogFrameDto.md) & \\{ `createdAt`: `string`; `id`: `string`; `userId?`: `string` \\| `null`; \\}\n\nOne entry of a session's protocol log.\n\nSerializes as `{\"userId\": ..., \"direction\": ..., \"content\": ...}` - the\nframe's own two fields, flattened in beside the attribution, which is the\nsame shape a recorded session's JSONL carries. A reader can deserialize the\n`direction`/`content` pair straight back into the fold's own log type\nrather than through a transport vocabulary of its own.\n\n`agentSessionId` is not repeated per entry: every entry in a response\nbelongs to the session named once at the top.\n\n`Deserialize` is for the wire-contract tests only - nothing server-side\ndecodes its own response type.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | When the log recorded the frame. The frame itself carries no time, so this comes from the log row. It is what a reader has to order these against anything else it is showing beside them - the fold derives an order among the messages of one session and nothing more. |\n| `id` | `string` | Durable transport row identity; together with `createdAt`, its order cursor. |\n| `userId?` | `string` \\| `null` | The user whose action produced the frame, absent when no user did. Only prompts carry one, and only when the frame was attributed at the time - a replayed or recorded session's are anonymous. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md -->\n# Type Alias: AgentSessionLogResponse\n\n> **AgentSessionLogResponse** = \\{ `bot`: [`SessionBot`](SessionBot.md); `entries`: [`AgentSessionLogEntryDto`](AgentSessionLogEntryDto.md)[]; \\}\n\nResponse body for one session's raw protocol log.\n\nA wrapper rather than a bare array so that anything which is about the\nresponse rather than about a frame has somewhere to go later without\nbreaking every client.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bot\"></a> `bot` | [`SessionBot`](SessionBot.md) | The agent whose messages the log derives. Here because a client renders those messages and cannot otherwise work out who sent them: the sender of an agent message is this session's bot, and nothing else names it. |\n| <a id=\"property-entries\"></a> `entries` | [`AgentSessionLogEntryDto`](AgentSessionLogEntryDto.md)[] | Effective history in ascending `(createdAt, id)` order. The first row is the inclusive history boundary cursor: buffered rows before it are obsolete. Reconcile snapshot overlap by row ID, never content. An empty history has no boundary or overlapping rows. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md -->\n# Type Alias: AgentSessionResponse\n\n> **AgentSessionResponse** = \\{ `acpSessionId?`: `string` \\| `null`; `botId`: `string`; `canEdit`: `boolean`; `createdAt`: `string`; `external?`: `null` \\| [`ExternalSessionResponse`](ExternalSessionResponse.md); `harness`: `string`; `id`: `string`; `instructions?`: `string` \\| `null`; `isArchived`: `boolean`; `model`: `string`; `modifiedAt`: `string`; `name`: `string`; `originatingMessageId?`: `string` \\| `null`; `ownerId`: `string`; `pullRequestUrl?`: `string` \\| `null`; `repoUrl?`: `string` \\| `null`; `sandboxSize`: [`SandboxSize`](SandboxSize.md); `status`: [`SessionStatusDto`](SessionStatusDto.md); `taskId?`: `string` \\| `null`; `threadChannelId?`: `string` \\| `null`; `threadId?`: `string` \\| `null`; `threadParent?`: `null` \\| [`MessageParent`](MessageParent.md); `workspace`: `string`; \\}\n\nResponse body describing an agent session.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-acpsessionid\"></a> `acpSessionId?` | `string` \\| `null` | The ACP session id, if one exists. |\n| <a id=\"property-botid\"></a> `botId` | `string` | The bot running the agent. |\n| <a id=\"property-canedit\"></a> `canEdit` | `boolean` | Whether the caller may drive the session - prompt it, answer its questions, stop it - rather than only watch. Edit access; the creator owns the session, so a create response always says so. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the session was created. |\n| <a id=\"property-external\"></a> `external?` | `null` \\| [`ExternalSessionResponse`](ExternalSessionResponse.md) | - |\n| <a id=\"property-harness\"></a> `harness` | `string` | Harness slug. |\n| <a id=\"property-id\"></a> `id` | `string` | The session id. |\n| <a id=\"property-instructions\"></a> `instructions?` | `string` \\| `null` | Instructions the session's runtime works under, when any were stated at creation. Absent otherwise, so existing payloads are unchanged. |\n| <a id=\"property-isarchived\"></a> `isArchived` | `boolean` | Whether the session is archived and read-only. |\n| <a id=\"property-model\"></a> `model` | `string` | Model slug. |\n| <a id=\"property-modifiedat\"></a> `modifiedAt` | `string` | When the session was last modified. |\n| <a id=\"property-name\"></a> `name` | `string` | User-facing session name. |\n| <a id=\"property-originatingmessageid\"></a> `originatingMessageId?` | `string` \\| `null` | The exact message that invoked the bot, if any. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | The user who created and owns the session. |\n| <a id=\"property-pullrequesturl\"></a> `pullRequestUrl?` | `string` \\| `null` | The session's linked pull request. |\n| <a id=\"property-repourl\"></a> `repoUrl?` | `string` \\| `null` | The repository the session works with, when one was stated. |\n| <a id=\"property-sandboxsize\"></a> `sandboxSize` | [`SandboxSize`](SandboxSize.md) | Compute tier of the managed sandbox. |\n| <a id=\"property-status\"></a> `status` | [`SessionStatusDto`](SessionStatusDto.md) | The session's status. |\n| <a id=\"property-taskid\"></a> `taskId?` | `string` \\| `null` | The Macro task the session was linked to. |\n| <a id=\"property-threadchannelid\"></a> `threadChannelId?` | `string` \\| `null` | The channel `thread_id` lives in, when the session was spawned from a channel thread. Derived from `thread_parent`. |\n| <a id=\"property-threadid\"></a> `threadId?` | `string` \\| `null` | The root message of the thread the session was created from, if any. |\n| <a id=\"property-threadparent\"></a> `threadParent?` | `null` \\| [`MessageParent`](MessageParent.md) | - |\n| <a id=\"property-workspace\"></a> `workspace` | `string` | The directory the session's harness runs in on its runtime. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSetConfigOptionAction.md -->\n# Type Alias: AgentSetConfigOptionAction\n\n> **AgentSetConfigOptionAction** = \\{ `configId`: `string`; `value`: `string`; \\}\n\nAsk the agent to change one advertised select-style session setting.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-configid\"></a> `configId` | `string` | Opaque ACP config id advertised by the agent. |\n| <a id=\"property-value\"></a> `value` | `string` | Opaque select value advertised for that config option. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSetModelAction.md -->\n# Type Alias: AgentSetModelAction\n\n> **AgentSetModelAction** = \\{ `model`: `string`; \\}\n\nAsk the agent to run on a different model from here on.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-model\"></a> `model` | `string` | The model slug the agent should switch to. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md -->\n# Type Alias: AnswerToolApprovalResponse\n\n> **AnswerToolApprovalResponse** = \\{ `status`: [`ToolApprovalStatusDto`](ToolApprovalStatusDto.md); \\}\n\nResponse body for answering a held tool call.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-status\"></a> `status` | [`ToolApprovalStatusDto`](ToolApprovalStatusDto.md) | Where the call stands now. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/BotId.md -->\n# Type Alias: BotId\n\n> **BotId** = `string`\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CaptureAttemptDto.md -->\n# Type Alias: CaptureAttemptDto\n\n> **CaptureAttemptDto** = \\{ `error?`: `string` \\| `null`; `finishedAt?`: `string` \\| `null`; `outcome?`: `null` \\| [`CaptureOutcomeDto`](CaptureOutcomeDto.md); `startedAt`: `string`; \\}\n\nThe latest capture attempt.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Why it did not capture, in a sentence the user can read. |\n| <a id=\"property-finishedat\"></a> `finishedAt?` | `string` \\| `null` | When it ended; absent while it runs. |\n| <a id=\"property-outcome\"></a> `outcome?` | `null` \\| [`CaptureOutcomeDto`](CaptureOutcomeDto.md) | - |\n| <a id=\"property-startedat\"></a> `startedAt` | `string` | When it started. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CaptureOutcomeDto.md -->\n# Type Alias: CaptureOutcomeDto\n\n> **CaptureOutcomeDto** = `\"captured\"` \\| `\"not_ready\"` \\| `\"failed\"`\n\nHow the latest capture attempt ended, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangedFileDto.md -->\n# Type Alias: ChangedFileDto\n\n> **ChangedFileDto** = \\{ `additions`: `number`; `binary`: `boolean`; `deletions`: `number`; `kind`: [`FileChangeKindDto`](FileChangeKindDto.md); `patchOmitted`: `boolean`; `path`: `string`; `previousPath?`: `string` \\| `null`; \\}\n\nOne changed file.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions` | `number` | Lines added. |\n| <a id=\"property-binary\"></a> `binary` | `boolean` | The diff carries no text for this file. |\n| <a id=\"property-deletions\"></a> `deletions` | `number` | Lines removed. |\n| <a id=\"property-kind\"></a> `kind` | [`FileChangeKindDto`](FileChangeKindDto.md) | What happened to the file. |\n| <a id=\"property-patchomitted\"></a> `patchOmitted` | `boolean` | The file's hunks were left out of the patch to fit the size budget. |\n| <a id=\"property-path\"></a> `path` | `string` | The file's path after the change, or before it for a deletion. |\n| <a id=\"property-previouspath\"></a> `previousPath?` | `string` \\| `null` | Where a renamed file came from. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangesetDto.md -->\n# Type Alias: ChangesetDto\n\n> **ChangesetDto** = \\{ `additions`: `number`; `base`: [`GitRefDto`](GitRefDto.md); `capturedAt`: `string`; `deletions`: `number`; `files`: [`ChangedFileDto`](ChangedFileDto.md)[]; `head`: [`GitRefDto`](GitRefDto.md); `id`: `string`; `patchBytes`: `number`; `repository?`: `string` \\| `null`; `source`: [`ChangesetSourceDto`](ChangesetSourceDto.md); `truncated`: `boolean`; \\}\n\nOne changeset: the files a patch touches and what happened to each.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions` | `number` | Lines added across all files. |\n| <a id=\"property-base\"></a> `base` | [`GitRefDto`](GitRefDto.md) | The side the work started from. |\n| <a id=\"property-capturedat\"></a> `capturedAt` | `string` | When the diff was taken. |\n| <a id=\"property-deletions\"></a> `deletions` | `number` | Lines removed across all files. |\n| <a id=\"property-files\"></a> `files` | [`ChangedFileDto`](ChangedFileDto.md)[] | Every changed file, in patch order. |\n| <a id=\"property-head\"></a> `head` | [`GitRefDto`](GitRefDto.md) | The side carrying the work. |\n| <a id=\"property-id\"></a> `id` | `string` | The changeset's id; a different id means different changes. |\n| <a id=\"property-patchbytes\"></a> `patchBytes` | `number` | Size of the patch the matching patch route serves; zero when nothing changed. |\n| <a id=\"property-repository\"></a> `repository?` | `string` \\| `null` | `https://github.com/owner/name`, when known. |\n| <a id=\"property-source\"></a> `source` | [`ChangesetSourceDto`](ChangesetSourceDto.md) | Where the diff was read from. |\n| <a id=\"property-truncated\"></a> `truncated` | `boolean` | Some files' hunks were left out of the patch. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangesetSourceDto.md -->\n# Type Alias: ChangesetSourceDto\n\n> **ChangesetSourceDto** = `\"github_pull_request\"`\n\nThe source of a changeset's diff, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md -->\n# Type Alias: CodingPreferencesBody\n\n> **CodingPreferencesBody** = \\{ `createTasks`: `boolean`; `openPullRequests`: `boolean`; \\}\n\nRequest or response body for the caller's coding preferences.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createtasks\"></a> `createTasks` | `boolean` | Whether new coding sessions research prior work and link a Macro task. |\n| <a id=\"property-openpullrequests\"></a> `openPullRequests` | `boolean` | Whether new coding sessions deliver their work as a pull request. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ControlResponse.md -->\n# Type Alias: ControlResponse\n\n> **ControlResponse** = \\{ `actionId`: [`AgentActionId`](AgentActionId.md); `status`: [`ControlStatusDto`](ControlStatusDto.md); \\}\n\nResponse body for a control operation.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | [`AgentActionId`](AgentActionId.md) | Matches `requestId` on the folded message this action derives once it dispatches, and names the queue entry until then. The caller's own `actionId` when it supplied one; a freshly minted id otherwise. |\n| <a id=\"property-status\"></a> `status` | [`ControlStatusDto`](ControlStatusDto.md) | Whether the action went out or waits in the queue. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ControlStatusDto.md -->\n# Type Alias: ControlStatusDto\n\n> **ControlStatusDto** = `\"sent\"` \\| `\"queued\"`\n\nWhat accepting a control operation did with it, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ConversationTurnState.md -->\n# Type Alias: ConversationTurnState\n\n> **ConversationTurnState** = `\"queued\"` \\| `\"running\"` \\| `\"succeeded\"` \\| `\"failed\"` \\| `\"stopped\"` \\| `\"interrupted\"`\n\nThe state of one source message, retained after completion for deduplication.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/DocumentId.md -->\n# Type Alias: DocumentId\n\n> **DocumentId** = `string`\n\nA validated document identifier. Historical document ids need not be UUIDs.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationAnswer.md -->\n# Type Alias: ElicitationAnswer\n\n> **ElicitationAnswer** = \\{ `action`: `\"accept\"`; `content?`: \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null`; \\} \\| \\{ `action`: `\"decline\"`; \\} \\| \\{ `action`: `\"cancel\"`; \\}\n\nWhat the user decided about an elicitation. Mirrors ACP's three actions;\nthere is no `Other` because we never originate an action we do not know.\n\n## Union Members\n\n### Type Literal\n\n\\{ `action`: `\"accept\"`; `content?`: \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `action` | `\"accept\"` | - |\n| `content?` | \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null` | Form: the submitted values keyed by property. URL: omitted. |\n\n***\n\n### Type Literal\n\n\\{ `action`: `\"decline\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `action`: `\"cancel\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationContentValue.md -->\n# Type Alias: ElicitationContentValue\n\n> **ElicitationContentValue** = `string` \\| `boolean` \\| `number` \\| `number` \\| `string`[]\n\nA value ACP accepts in an elicitation answer.\n\nMirrors ACP's `ElicitationContentValue` so that the contract a caller\nanswers against is the closed union ACP will accept, rather than arbitrary\nJSON narrowed on the way out. An object, a null, or a mixed array is\nrefused when the request is deserialized - where the caller learns of it -\ninstead of at send time, when the elicitation slot has already been\nreleased.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationRequestId.md -->\n# Type Alias: ElicitationRequestId\n\n> **ElicitationRequestId** = `number` \\| `string`\n\nThe JSON-RPC id of an agent's `elicitation/create` request, carried whole\nso the answer echoes exactly what the agent sent.\n\nAgents pick these, not us: Claude Code counts from `0`, others use\nstrings. `null` is not a legal id for a request that expects a response,\nso it is not representable here.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionActivity.md -->\n# Type Alias: ExecutionActivity\n\n> **ExecutionActivity** = \\{ `id`: `number`; `label`: `string`; `status`: [`RecordedCallStatus`](RecordedCallStatus.md); \\}\n\nA bounded SDK operation observed during execution; not an authorization or write receipt.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` | Request identity within the execution. |\n| <a id=\"property-label\"></a> `label` | `string` | Server-selected label from the generated operation catalog. |\n| <a id=\"property-status\"></a> `status` | [`RecordedCallStatus`](RecordedCallStatus.md) | Observed request state; unfinished operations have unknown outcomes. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionId.md -->\n# Type Alias: ExecutionId\n\n> **ExecutionId** = `string`\n\nCaller-selected UUID persisted in tool input before execution begins.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md -->\n# Type Alias: ExecutionRecord\n\n> **ExecutionRecord** = \\{ `activity?`: [`ExecutionActivity`](ExecutionActivity.md)[]; `activityTruncated?`: `boolean`; `calls`: [`RecordedToolCall`](RecordedToolCall.md)[]; `error?`: `string` \\| `null`; `executionId`: [`ExecutionId`](ExecutionId.md); `result?`: `unknown`; `source`: `string`; `status`: [`ExecutionStatus`](ExecutionStatus.md); \\}\n\nDurable source and final outcome, with historical bridge calls when present.\nThe full journal is not included in the model's tool result.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-activity\"></a> `activity?` | [`ExecutionActivity`](ExecutionActivity.md)[] | Advisory SDK operation activity, without arguments or response contents. |\n| <a id=\"property-activitytruncated\"></a> `activityTruncated?` | `boolean` | Additional request activity was omitted at the bounded observation limit. |\n| <a id=\"property-calls\"></a> `calls` | [`RecordedToolCall`](RecordedToolCall.md)[] | Historical bridge calls. Direct HTTP executions leave this empty. |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Safe execution failure text. |\n| <a id=\"property-executionid\"></a> `executionId` | [`ExecutionId`](ExecutionId.md) | Execution identity. |\n| <a id=\"property-result\"></a> `result?` | `unknown` | JSON returned by the program, if successful. |\n| <a id=\"property-source\"></a> `source` | `string` | The submitted JavaScript module. |\n| <a id=\"property-status\"></a> `status` | [`ExecutionStatus`](ExecutionStatus.md) | Overall execution state. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionStatus.md -->\n# Type Alias: ExecutionStatus\n\n> **ExecutionStatus** = `\"running\"` \\| `\"succeeded\"` \\| `\"failed\"` \\| `\"cancelled\"` \\| `\"timed_out\"`\n\nThe recorded outcome of a program.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExternalSessionResponse.md -->\n# Type Alias: ExternalSessionResponse\n\n> **ExternalSessionResponse** = \\{ `name?`: `string` \\| `null`; `provider`: `string`; `url?`: `string` \\| `null`; \\}\n\nThe provider-side identity of an externally-served session.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The provider's display name for the agent, when it reported one. |\n| <a id=\"property-provider\"></a> `provider` | `string` | Which provider serves the session, e.g. `cursor`. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The agent's page on the provider's site, for a client to link out to. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/FileChangeKindDto.md -->\n# Type Alias: FileChangeKindDto\n\n> **FileChangeKindDto** = `\"added\"` \\| `\"modified\"` \\| `\"deleted\"` \\| `\"renamed\"`\n\nWhat happened to a file, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/GitRefDto.md -->\n# Type Alias: GitRefDto\n\n> **GitRefDto** = \\{ `name?`: `string` \\| `null`; `sha?`: `string` \\| `null`; \\}\n\nOne end of the compared range.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The branch name, when known. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The commit, when known. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LogDirectionDto.md -->\n# Type Alias: LogDirectionDto\n\n> **LogDirectionDto** = `\"to_server\"` \\| `\"to_runtime\"`\n\nWhich way a logged frame travelled, mirroring [`Message`]'s discriminant.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LogFrameDto.md -->\n# Type Alias: LogFrameDto\n\n> **LogFrameDto** = \\{ `content`: \\{\\[`key`: `string`\\]: `unknown`; \\}; `direction`: [`LogDirectionDto`](LogDirectionDto.md); \\}\n\nThe two fields [`AgentSessionLogEntryDto`] flattens in.\n\nSchema only. Nothing constructs one: the entry serializes through\n[`Message`], and this exists so the generated clients see `direction` and\n`content` as named fields instead of an open map. A hand-built copy could\ndrift from the fold's wire format, and the point of the endpoint is that it\ncannot - so this describes that format without being able to produce it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-content\"></a> `content` | \\{\\[`key`: `string`\\]: `unknown`; \\} | The protocol envelope, verbatim. Opaque here: it is Agent Runtime Protocol, whose shape belongs to the fold rather than this endpoint. |\n| <a id=\"property-direction\"></a> `direction` | [`LogDirectionDto`](LogDirectionDto.md) | Which way the frame travelled. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `id`: `string`; `type`: `\"channel\"`; \\} \\| \\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\} \\| \\{ `id`: `string`; `type`: `\"initiative\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_company\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_contact\"`; \\} \\| \\{ `id`: `string`; `type`: `\"call\"`; \\}\n\nThe entity whose permissions and lifecycle govern a message.\n\n## Union Members\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A channel, including direct messages. |\n| `type` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | [`DocumentId`](DocumentId.md) | A document, including tasks and PDFs. |\n| `type` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | An initiative, presented as a project in the application. |\n| `type` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_company\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM company. |\n| `type` | `\"crm_company\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_contact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM contact. |\n| `type` | `\"crm_contact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A video call and its persistent chat thread. |\n| `type` | `\"call\"` | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PermissionAnswer.md -->\n# Type Alias: PermissionAnswer\n\n> **PermissionAnswer** = \\{ `kind`: `\"selected\"`; `optionId`: `string`; \\} \\| \\{ `kind`: `\"cancelled\"`; \\}\n\nThe decision carried by an [`AgentPermissionAction`].\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"selected\"`; `optionId`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"selected\"` | - |\n| `optionId` | `string` | The chosen option's id, as the agent listed it. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"cancelled\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PromptAttachment.md -->\n# Type Alias: PromptAttachment\n\n> **PromptAttachment** = \\{ `mimeType?`: `string` \\| `null`; `name`: `string`; `size?`: `number` \\| `null`; `uri`: `string`; \\}\n\nA file the prompt refers to, by where the agent can fetch it.\n\nMirrors ACP's `resource_link` content block, which every agent must\naccept: bytes never ride the prompt, only a URI (a static file service URL\nin practice) with enough metadata for a client to render a chip and for\nthe agent to decide whether to fetch it. Keeping the wire shape ACP-native\nmeans the harness translates without resolving anything, and the fold\nreads the same fields back off the logged frame.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-mimetype\"></a> `mimeType?` | `string` \\| `null` | The file's media type, when known. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name, typically the original file name. |\n| <a id=\"property-size\"></a> `size?` | `number` \\| `null` | Size in bytes, when known. |\n| <a id=\"property-uri\"></a> `uri` | `string` | Where the agent can fetch the file. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md -->\n# Type Alias: PullRequestLinkSource\n\n> **PullRequestLinkSource** = `\"agent\"` \\| `\"user\"`\n\nWho associated a pull request with a session.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/QueuedActionDto.md -->\n# Type Alias: QueuedActionDto\n\n> **QueuedActionDto** = \\{ `actionId`: [`AgentActionId`](AgentActionId.md); `actorUserId?`: `string` \\| `null`; `attachments?`: [`PromptAttachment`](PromptAttachment.md)[]; `createdAt`: `string`; `kind`: `string`; `prompt?`: `string` \\| `null`; \\}\n\nOne action waiting in a session's queue.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | [`AgentActionId`](AgentActionId.md) | The id the action was accepted under. |\n| <a id=\"property-actoruserid\"></a> `actorUserId?` | `string` \\| `null` | The user who queued it, absent when a bot acted on nobody's behalf. |\n| <a id=\"property-attachments\"></a> `attachments?` | [`PromptAttachment`](PromptAttachment.md)[] | Files the prompt refers to, for prompts only. Kept through an edit, which replaces the text alone. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When it was accepted. |\n| <a id=\"property-kind\"></a> `kind` | `string` | What kind of action waits - `prompt` or `compact`; only turn-occupying actions are ever queued. |\n| <a id=\"property-prompt\"></a> `prompt?` | `string` \\| `null` | The prompt's raw text, present for prompts only. What an edit replaces. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/RecordedCallStatus.md -->\n# Type Alias: RecordedCallStatus\n\n> **RecordedCallStatus** = `\"running\"` \\| `\"completed\"` \\| `\"failed\"` \\| `\"unknown\"`\n\nA dispatch result; unfinished work is never reported as success.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/RecordedToolCall.md -->\n# Type Alias: RecordedToolCall\n\n> **RecordedToolCall** = \\{ `error?`: `string` \\| `null`; `id`: `string`; `input`: `unknown`; `name`: `string`; `output?`: `unknown`; `outputOmitted`: `boolean`; `status`: [`RecordedCallStatus`](RecordedCallStatus.md); \\}\n\nA real inner call, recorded by trusted dispatch for the existing renderers.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Safe tool failure, if one was returned. |\n| <a id=\"property-id\"></a> `id` | `string` | Stable, execution-scoped component identity. |\n| <a id=\"property-input\"></a> `input` | `unknown` | Arguments passed to the actual tool. |\n| <a id=\"property-name\"></a> `name` | `string` | Canonical Macro tool name from the allowlisted registry. |\n| <a id=\"property-output\"></a> `output?` | `unknown` | Original tool output, retained independently of the program's return value. |\n| <a id=\"property-outputomitted\"></a> `outputOmitted` | `boolean` | Whether the response was omitted to keep the durable journal bounded. |\n| <a id=\"property-status\"></a> `status` | [`RecordedCallStatus`](RecordedCallStatus.md) | A started call that never replied has an unknown side-effect outcome. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewId.md -->\n# Type Alias: ReviewId\n\n> **ReviewId** = `string`\n\nPersisted review identity.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewItem.md -->\n# Type Alias: ReviewItem\n\n> **ReviewItem** = \\{ `draft`: `unknown`; `error?`: `string` \\| `null`; `id`: `string`; `result?`: `unknown`; `status`: [`ReviewItemStatus`](ReviewItemStatus.md); \\}\n\nOne editable item and its durable outcome.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-draft\"></a> `draft` | `unknown` | Validated arguments for the existing composer/action. |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Failure or uncertainty description. |\n| <a id=\"property-id\"></a> `id` | `string` | Stable item identity across stack navigation and edits. |\n| <a id=\"property-result\"></a> `result?` | `unknown` | Actual backend response, never a model assertion. |\n| <a id=\"property-status\"></a> `status` | [`ReviewItemStatus`](ReviewItemStatus.md) | Current outcome. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md -->\n# Type Alias: ReviewItemStatus\n\n> **ReviewItemStatus** = `\"pending\"` \\| `\"submitting\"` \\| `\"completed\"` \\| `\"dismissed\"` \\| `\"unknown\"`\n\nA review item never retries an ambiguous external result automatically.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewKind.md -->\n# Type Alias: ReviewKind\n\n> **ReviewKind** = `\"email\"` \\| `\"calendar\"`\n\nThe component and action used to finish a review.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewRecord.md -->\n# Type Alias: ReviewRecord\n\n> **ReviewRecord** = \\{ `executionId?`: `null` \\| [`ExecutionId`](ExecutionId.md); `id`: [`ReviewId`](ReviewId.md); `items`: [`ReviewItem`](ReviewItem.md)[]; `kind`: [`ReviewKind`](ReviewKind.md); `notificationAttemptAt?`: `number` \\| `null`; `notificationId?`: `string` \\| `null`; `presentedAt?`: `number` \\| `null`; `revision`: `number`; `sessionId`: `string`; `title`: `string`; `updatedAt`: `number`; \\}\n\nFull UI record, fetched outside the model context.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-executionid\"></a> `executionId?` | `null` \\| [`ExecutionId`](ExecutionId.md) | - |\n| <a id=\"property-id\"></a> `id` | [`ReviewId`](ReviewId.md) | Review identity. |\n| <a id=\"property-items\"></a> `items` | [`ReviewItem`](ReviewItem.md)[] | Drafts and per-item outcomes. |\n| <a id=\"property-kind\"></a> `kind` | [`ReviewKind`](ReviewKind.md) | Component kind. |\n| <a id=\"property-notificationattemptat\"></a> `notificationAttemptAt?` | `number` \\| `null` | Most recent delivery claim, allowing retry after a replica stops. |\n| <a id=\"property-notificationid\"></a> `notificationId?` | `string` \\| `null` | Stable queued-action identity until the outcome has reached the session. A failed notification may be retried without repeating external actions. |\n| <a id=\"property-presentedat\"></a> `presentedAt?` | `number` \\| `null` | Durable presentation acknowledgment, separate from user decisions. |\n| <a id=\"property-revision\"></a> `revision` | `number` | Compare-and-swap revision for edits and submissions. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Owning session. |\n| <a id=\"property-title\"></a> `title` | `string` | Stack label. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `number` | Milliseconds since epoch of the last state change. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SandboxSize.md -->\n# Type Alias: SandboxSize\n\n> **SandboxSize** = `\"small\"` \\| `\"default\"` \\| `\"large\"`\n\nNamed compute tier for a managed sandbox.\n\nThe API and database store the name. CPU, RAM, and disk live in\n`crates/agent_harness/sandbox_sizes.json`.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SessionBot.md -->\n# Type Alias: SessionBot\n\n> **SessionBot** = \\{ `avatarUrl?`: `string` \\| `null`; `handle`: `string`; `id`: [`BotId`](BotId.md); `name`: `string`; \\}\n\nThe agent behind a session, as much of it as rendering a message needs.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatarurl\"></a> `avatarUrl?` | `string` \\| `null` | Avatar, when it has one. |\n| <a id=\"property-handle\"></a> `handle` | `string` | Stable `@` handle, without a leading `@`. |\n| <a id=\"property-id\"></a> `id` | [`BotId`](BotId.md) | The bot's id. A message it sent has `\"bot\\|{id}\"` as its sender. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SessionStatusDto.md -->\n# Type Alias: SessionStatusDto\n\n> **SessionStatusDto** = \\{ `kind`: `\"no_messages\"`; \\} \\| \\{ `event`: `string`; `kind`: `\"event\"`; \\} \\| \\{ `kind`: `\"disconnected\"`; \\}\n\nTransport representation of a session's status, mirroring\n[`SessionStatus`].\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"no_messages\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `event`: `string`; `kind`: `\"event\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `event` | `string` | The wire name of the system event, e.g. `acp_ready`. |\n| `kind` | `\"event\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"disconnected\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ToolApprovalAnswerDto.md -->\n# Type Alias: ToolApprovalAnswerDto\n\n> **ToolApprovalAnswerDto** = `\"approve\"` \\| `\"approve_and_remember\"` \\| `\"deny\"` \\| `\"cancel\"`\n\nHow a person answers a held tool call.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ToolApprovalStatusDto.md -->\n# Type Alias: ToolApprovalStatusDto\n\n> **ToolApprovalStatusDto** = `\"pending\"` \\| `\"approved\"` \\| `\"denied\"` \\| `\"cancelled\"` \\| `\"expired\"`\n\nWhere a held tool call stands once answered.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- src/entities/agent-sessions/agent-session/classes/AgentSession.md -->\n# Class: AgentSession\n\nA managed or externally hosted coding-agent session.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | Access requests and direct user grants. | - |\n| <a id=\"property-codeexecutions\"></a> `codeExecutions` | `readonly` | \\{ `byId`: (`id`) => [`CodeExecution`](../../code-execution/classes/CodeExecution.md); \\} | Saved code executions scoped to this session. Handle construction makes no request. | - |\n| `codeExecutions.byId` | `public` | (`id`) => [`CodeExecution`](../../code-execution/classes/CodeExecution.md) | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the session was created. | - |\n| <a id=\"property-harness\"></a> `harness` | `readonly` | () => `Promise`\\<`string`\\> | The agent harness implementation serving the session. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-instructions\"></a> `instructions` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Instructions the session's runtime works under, when any were stated at creation. Fixed for the session's life. | - |\n| <a id=\"property-isarchived\"></a> `isArchived` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the session is archived and read-only. | - |\n| <a id=\"property-model\"></a> `model` | `readonly` | () => `Promise`\\<`string`\\> | The model currently configured for the session. | - |\n| <a id=\"property-modifiedat\"></a> `modifiedAt` | `readonly` | () => `Promise`\\<`string`\\> | When the session was last modified. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | The session's user-facing display name. | - |\n| <a id=\"property-repourl\"></a> `repoUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The repository the agent works with, when one was supplied. | - |\n| <a id=\"property-reviews\"></a> `reviews` | `readonly` | \\{ `byId`: (`id`) => [`SessionReview`](../../review/classes/SessionReview.md); `create`: (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\>; \\} | Persisted reviews scoped to this session, with or without a code execution. | - |\n| `reviews.byId` | `public` | (`id`) => [`SessionReview`](../../review/classes/SessionReview.md) | - | - |\n| `reviews.create` | `public` | (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\> | - | - |\n| <a id=\"property-sandboxsize\"></a> `sandboxSize` | `readonly` | () => `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\> | Compute tier of the managed sandbox. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`SessionStatusDto`](../../../../../generated/agent-harness/types.gen/type-aliases/SessionStatusDto.md)\\> | The session's latest runtime status. | - |\n| <a id=\"property-workspace\"></a> `workspace` | `readonly` | () => `Promise`\\<`string`\\> | The directory in which the agent harness runs. | - |\n\n## Methods\n\n### archive()\n\n> **archive**(): `Promise`\\<`void`\\>\n\nArchive this session, making it read-only until unarchived.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### changes()\n\n> **changes**(): `Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\nRead the latest captured GitHub pull request changes and capture status.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\n***\n\n### changesPatch()\n\n> **changesPatch**(): `Promise`\\<`string`\\>\n\nRead the unified diff of the latest captured changeset.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### control()\n\n> **control**(`action`): `Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\nSend a prompt or lifecycle operation to the live agent session.\n\nThe returned `actionId` matches `requestId` on the folded message the\naction derives once it dispatches. A `queued` status means a turn was\nrunning: the action waits in the session's queue ([queue](#queue)) and\ndispatches when that turn ends.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `action` | [`AgentAction`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentAction.md) |\n\n#### Returns\n\n`Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this session and any live resources it owns.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### linkPullRequest()\n\n> **linkPullRequest**(`url`): `Promise`\\<`void`\\>\n\nLink the GitHub pull request at `url` to this session. Linking one that\nis already linked changes nothing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### log()\n\n> **log**(): `Promise`\\<[`AgentSessionLogResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md)\\>\n\nRead the complete raw protocol log for this session.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionLogResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md)\\>\n\n***\n\n### prompt()\n\n> **prompt**(`text`, `attachments?`): `Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\nSend a prompt to the session — sugar over [control](#control).\n\n`attachments` are files the prompt refers to, each by a URL the agent\ncan fetch (a static file service URL in practice); they reach the agent\nas ACP `resource_link` blocks after the text.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `text` | `string` |\n| `attachments?` | [`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[] |\n\n#### Returns\n\n`Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\n***\n\n### pullRequests()\n\n> **pullRequests**(): `Promise`\\<[`SessionPullRequest`](../type-aliases/SessionPullRequest.md)[]\\>\n\nThe GitHub pull requests linked to this session: the one its agent\nopened and any a person linked, oldest first.\n\n#### Returns\n\n`Promise`\\<[`SessionPullRequest`](../type-aliases/SessionPullRequest.md)[]\\>\n\n***\n\n### queue()\n\n> **queue**(): `Promise`\\<[`QueuedAction`](../../queued-action/classes/QueuedAction.md)[]\\>\n\nThe actions waiting to dispatch in this session, oldest first. Each can\nbe edited or removed until it dispatches.\n\n#### Returns\n\n`Promise`\\<[`QueuedAction`](../../queued-action/classes/QueuedAction.md)[]\\>\n\n***\n\n### refreshChanges()\n\n> **refreshChanges**(): `Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\nRequest a fresh capture and return the current state while it runs.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename this session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setSandboxSize()\n\n> **setSandboxSize**(`size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nResize this session's sandbox and remember the size as the owner's default.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### toolApprovalById()\n\n> **toolApprovalById**(`id`): [`ToolApproval`](../../tool-approval/classes/ToolApproval.md)\n\nConstruct an approval handle scoped to this session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`ToolApproval`](../../tool-approval/classes/ToolApproval.md)\n\n***\n\n### unarchive()\n\n> **unarchive**(): `Promise`\\<`void`\\>\n\nRestore an archived session so it can be edited and prompted again.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### unlinkPullRequest()\n\n> **unlinkPullRequest**(`url`): `Promise`\\<`void`\\>\n\nUnlink a GitHub pull request a person linked to this session. The pull\nrequest the session's agent opened stays linked.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### updateSharePermissions()\n\n> **updateSharePermissions**(`options`): `Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nReplace sharing grants.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `AgentSession`\n\nA handle to an agent session by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`AgentSession`\n\n***\n\n### codingPreferences()\n\n> `static` **codingPreferences**(`client`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nWhat the caller's new coding sessions are told to do beyond their assignment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### createManaged()\n\n> `static` **createManaged**(`client`, `opts?`): `Promise`\\<`AgentSession`\\>\n\nCreate a managed session, optionally delivering its first prompt.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | [`CreateManagedSessionOptions`](../type-aliases/CreateManagedSessionOptions.md) |\n\n#### Returns\n\n`Promise`\\<`AgentSession`\\>\n\n***\n\n### defaultSandboxSize()\n\n> `static` **defaultSandboxSize**(`client`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nThe caller's default sandbox size for new `@coder` sessions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### forPullRequest()\n\n> `static` **forPullRequest**(`client`, `url`): `Promise`\\<`AgentSession`[]\\>\n\nThe sessions linked to the GitHub pull request at `url` that the caller\ncan view, oldest link first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`AgentSession`[]\\>\n\n***\n\n### repositories()\n\n> `static` **repositories**(`client`): `Promise`\\<[`SelectableRepository`](../type-aliases/SelectableRepository.md)[]\\>\n\nThe GitHub repositories the caller can hand a managed session: every\nrepository under an installation of Macro's GitHub App they or their\nteams made, sorted by `owner/name`. Empty when the App is installed\nnowhere they reach.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`SelectableRepository`](../type-aliases/SelectableRepository.md)[]\\>\n\n***\n\n### repositoryBranches()\n\n> `static` **repositoryBranches**(`client`, `repoUrl`): `Promise`\\<`string`[]\\>\n\nBranch names on one repository the caller can start a managed session\nfrom, in the order GitHub listed them. Empty when the repository has\nno commits yet. `repoUrl` is one of the URLs [AgentSession.repositories](#repositories)\nlists.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `repoUrl` | `string` |\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### setCodingPreferences()\n\n> `static` **setCodingPreferences**(`client`, `preferences`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nReplace the caller's coding preferences.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `preferences` | [`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md) |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### setDefaultSandboxSize()\n\n> `static` **setDefaultSandboxSize**(`client`, `size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nSet the caller's default sandbox size for the next `@coder` mention.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/CreateManagedSessionOptions.md -->\n# Type Alias: CreateManagedSessionOptions\n\n> **CreateManagedSessionOptions** = \\{ `instructions?`: `string`; `model?`: `string`; `prompt?`: `string`; `repoBranch?`: `string`; `repoUrl?`: `string`; \\}\n\nWhat a managed session is created with.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-instructions\"></a> `instructions?` | `string` | Instructions the session's runtime works under, fixed for its life. |\n| <a id=\"property-model\"></a> `model?` | `string` | The model the session runs on, instead of its persona's. The session's model from creation, read back as [AgentSession.model](../classes/AgentSession.md#property-model). |\n| <a id=\"property-prompt\"></a> `prompt?` | `string` | First prompt to deliver once the session is running. |\n| <a id=\"property-repobranch\"></a> `repoBranch?` | `string` | The branch the session starts on; needs `repoUrl`. Omitted, the repository's default branch. |\n| <a id=\"property-repourl\"></a> `repoUrl?` | `string` | The repository the session works on, as one of the URLs [AgentSession.repositories](../classes/AgentSession.md#repositories) lists for the caller. Omitted, the runtime chooses from the prompt. Honored for Cursor sessions. |\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/SelectableRepository.md -->\n# Type Alias: SelectableRepository\n\n> **SelectableRepository** = \\{ `defaultBranch?`: `string`; `url`: `string`; \\}\n\nA GitHub repository the caller can point a managed session at.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-defaultbranch\"></a> `defaultBranch?` | `string` | The branch its clones check out, and where a session starts unless `createManaged` names another. Absent for a repository with no commits. |\n| <a id=\"property-url\"></a> `url` | `string` | The canonical `https://github.com/owner/name` URL, as `createManaged` takes it. |\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/SessionPullRequest.md -->\n# Type Alias: SessionPullRequest\n\n> **SessionPullRequest** = \\{ `createdAt`: `string`; `githubKey`: `string`; `linkedBy?`: [`User`](../../../users/user/classes/User.md); `source`: [`PullRequestLinkSource`](../../../../../generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md); `url`: `string`; \\}\n\nA GitHub pull request linked to a session.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When it was linked. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The pull request's `owner/repo/pull/number` key. |\n| <a id=\"property-linkedby\"></a> `linkedBy?` | [`User`](../../../users/user/classes/User.md) | Who linked it, for pull requests a person linked. |\n| <a id=\"property-source\"></a> `source` | [`PullRequestLinkSource`](../../../../../generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md) | Whether the session's agent opened it or a person linked it. |\n| <a id=\"property-url\"></a> `url` | `string` | The pull request's GitHub URL. |\n\n\n<!-- src/entities/agent-sessions/code-execution/classes/CodeExecution.md -->\n# Class: CodeExecution\n\nA saved code execution belonging to one agent session.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | () => `Promise`\\<[`RecordedToolCall`](../../../../../generated/agent-harness/types.gen/type-aliases/RecordedToolCall.md)[]\\> | Legacy bridge calls; direct HTTP executions leave this empty. | - |\n| <a id=\"property-error\"></a> `error` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Execution failure text, when present. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-reviews\"></a> `reviews` | `readonly` | \\{ `create`: (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\>; `list`: () => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)[]\\>; \\} | Persistent UI blocks, independent of the execution lifetime. | - |\n| `reviews.create` | `public` | (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\> | - | - |\n| `reviews.list` | `public` | () => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)[]\\> | - | - |\n| <a id=\"property-source\"></a> `source` | `readonly` | () => `Promise`\\<`string`\\> | The submitted JavaScript module source. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`ExecutionStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionStatus.md)\\> | Saved execution state. Call refresh to observe subsequent changes. | - |\n\n## Methods\n\n### refresh()\n\n> **refresh**(): `Promise`\\<`CodeExecution`\\>\n\nReload the saved state, for example after a running execution completes.\n\n#### Returns\n\n`Promise`\\<`CodeExecution`\\>\n\n***\n\n### result()\n\n> **result**(): `Promise`\\<`unknown`\\>\n\nThe program's returned JSON; preserves an explicit null result.\n\n#### Returns\n\n`Promise`\\<`unknown`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nThe session this execution belongs to.\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `CodeExecution`\n\nConstruct a lazy execution handle within its owning session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`CodeExecution`\n\n\n<!-- src/entities/agent-sessions/code-execution/type-aliases/CodeResult.md -->\n# Type Alias: CodeResult\n\n> **CodeResult** = \\{ `data`: [`JsonValue`](JsonValue.md); `reviews`: \\{ `id`: `string`; `kind`: `\"email\"` \\| `\"calendar\"`; \\}[]; \\}\n\nJSON data returned to the model, plus references to independently saved UI.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-data\"></a> `data` | [`JsonValue`](JsonValue.md) |\n| <a id=\"property-reviews\"></a> `reviews` | \\{ `id`: `string`; `kind`: `\"email\"` \\| `\"calendar\"`; \\}[] |\n\n\n<!-- src/entities/agent-sessions/code-execution/type-aliases/JsonValue.md -->\n# Type Alias: JsonValue\n\n> **JsonValue** = `null` \\| `boolean` \\| `number` \\| `string` \\| `JsonValue`[] \\| \\{\\[`key`: `string`\\]: `JsonValue`; \\}\n\n\n<!-- src/entities/agent-sessions/conversation/classes/AgentConversation.md -->\n# Class: AgentConversation\n\nAn agent's conversation in one channel.\n\n## Constructors\n\n### Constructor\n\n> **new AgentConversation**(`client`, `channel`, `record`): `AgentConversation`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `channel` | [`Channel`](../../../channels/channel/classes/Channel.md) | Parent channel. |\n| `record` | [`AgentConversationDto`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentConversationDto.md) | - |\n\n#### Returns\n\n`AgentConversation`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-channel\"></a> `channel` | `readonly` | [`Channel`](../../../channels/channel/classes/Channel.md) | Parent channel. |\n\n## Methods\n\n### agent()\n\n> **agent**(): [`Agent`](../../../agents/agent/classes/Agent.md)\n\nThe agent taking part.\n\n#### Returns\n\n[`Agent`](../../../agents/agent/classes/Agent.md)\n\n***\n\n### sessions()\n\n> **sessions**(): \\{ `createdAt`: `string`; `isCurrent`: `boolean`; `session`: [`AgentSession`](../../agent-session/classes/AgentSession.md); \\}[]\n\nConversation sessions with their current flag.\n\n#### Returns\n\n\\{ `createdAt`: `string`; `isCurrent`: `boolean`; `session`: [`AgentSession`](../../agent-session/classes/AgentSession.md); \\}[]\n\n***\n\n### startFresh()\n\n> **startFresh**(`session`): `Promise`\\<`void`\\>\n\nStart a fresh conversation from one of its sessions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `agentId`: `string`; `channelId`: `string`; \\}\n\nSerialize scoped identity.\n\n#### Returns\n\n\\{ `agentId`: `string`; `channelId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `agentId` | `string` |\n| `channelId` | `string` |\n\n***\n\n### turns()\n\n> **turns**(): [`ConversationTurn`](ConversationTurn.md)[]\n\nRecorded conversation turns.\n\n#### Returns\n\n[`ConversationTurn`](ConversationTurn.md)[]\n\n\n<!-- src/entities/agent-sessions/conversation/classes/ConversationTurn.md -->\n# Class: ConversationTurn\n\nOne agent conversation turn, identified by its source message.\n\n## Constructors\n\n### Constructor\n\n> **new ConversationTurn**(`client`, `conversation`, `record`): `ConversationTurn`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `conversation` | [`AgentConversation`](AgentConversation.md) | Parent conversation. |\n| `record` | [`AgentConversationTurnDto`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentConversationTurnDto.md) | - |\n\n#### Returns\n\n`ConversationTurn`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-conversation\"></a> `conversation` | `readonly` | [`AgentConversation`](AgentConversation.md) | Parent conversation. |\n\n## Methods\n\n### retry()\n\n> **retry**(`actionId`): `Promise`\\<`void`\\>\n\nRetry with a caller persisted action nonce. Never retries automatically.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `actionId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nSession that handled this turn.\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### source()\n\n> **source**(): [`Message`](../../../channels/message/classes/Message.md)\n\nOriginating message.\n\n#### Returns\n\n[`Message`](../../../channels/message/classes/Message.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `channelId`: `string`; `sourceMessageId`: `string`; \\}\n\nSerialize scoped identity.\n\n#### Returns\n\n\\{ `channelId`: `string`; `sourceMessageId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `channelId` | `string` |\n| `sourceMessageId` | `string` |\n\n\n<!-- src/entities/agent-sessions/namespace/classes/AgentSessionNamespace.md -->\n# Class: AgentSessionNamespace\n\nEntry point for coding-agent sessions.\n\n## Constructors\n\n### Constructor\n\n> **new AgentSessionNamespace**(`client`): `AgentSessionNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`AgentSessionNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nA handle to an agent session by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### codingPreferences()\n\n> **codingPreferences**(): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nWhat the caller's new coding sessions are told to do beyond their assignment.\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### createManaged()\n\n> **createManaged**(`opts?`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\nCreate a managed agent session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`CreateManagedSessionOptions`](../../agent-session/type-aliases/CreateManagedSessionOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\n***\n\n### defaultSandboxSize()\n\n> **defaultSandboxSize**(): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nThe caller's default sandbox size for new `@coder` sessions.\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\nThe sessions linked to the GitHub pull request at `url` that the caller\ncan view.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\n***\n\n### repositories()\n\n> **repositories**(): `Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\nThe GitHub repositories the caller can hand a managed session, with the\nbranch each one's sessions start on by default.\n\n#### Returns\n\n`Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\n***\n\n### repositoryBranches()\n\n> **repositoryBranches**(`repoUrl`): `Promise`\\<`string`[]\\>\n\nBranch names on one repository the caller can start a managed session\nfrom. `repoUrl` is one of the URLs [AgentSessionNamespace.repositories](#repositories)\nlists.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `repoUrl` | `string` |\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### setCodingPreferences()\n\n> **setCodingPreferences**(`preferences`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nReplace the caller's coding preferences.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `preferences` | [`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md) |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### setDefaultSandboxSize()\n\n> **setDefaultSandboxSize**(`size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nSet the caller's default sandbox size for the next `@coder` mention.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n\n<!-- src/entities/agent-sessions/queued-action/classes/QueuedAction.md -->\n# Class: QueuedAction\n\nOne action waiting in an agent session's server-side queue: a prompt or a\ncompact accepted while a turn was running, dispatching when that turn\nends. Until then it can be edited (prompts only), steered, or removed; once\nit has dispatched, these actions answer 404 — there is no un-sending.\n\nList-sourced only - there is no per-action GET, only the queue snapshot -\nso this wraps whatever DTO the caller already has, the same shape\n`CrmComment` wraps a list-sourced record, rather than `MacroEntity`'s\nlazy-fetch-by-id.\n\n## Accessors\n\n### actionId\n\n#### Get Signature\n\n> **get** **actionId**(): `string`\n\nThe id the action was accepted under. Once it dispatches, this equals\n`requestId` on the folded message the action derives.\n\n##### Returns\n\n`string`\n\n***\n\n### actorUserId\n\n#### Get Signature\n\n> **get** **actorUserId**(): `string` \\| `undefined`\n\nThe user who queued it, absent when a bot acted on nobody's behalf.\n\n##### Returns\n\n`string` \\| `undefined`\n\n***\n\n### attachments\n\n#### Get Signature\n\n> **get** **attachments**(): [`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[]\n\nFiles the prompt refers to; empty for a compact. Kept through an edit.\n\n##### Returns\n\n[`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[]\n\n***\n\n### createdAt\n\n#### Get Signature\n\n> **get** **createdAt**(): `string`\n\nWhen the action was accepted, as an RFC 3339 timestamp.\n\n##### Returns\n\n`string`\n\n***\n\n### kind\n\n#### Get Signature\n\n> **get** **kind**(): `string`\n\n`prompt` or `compact`; only turn-occupying actions are ever queued.\n\n##### Returns\n\n`string`\n\n***\n\n### prompt\n\n#### Get Signature\n\n> **get** **prompt**(): `string` \\| `undefined`\n\nThe prompt's raw text, present for prompts only. What an edit replaces.\n\n##### Returns\n\n`string` \\| `undefined`\n\n## Methods\n\n### edit()\n\n> **edit**(`prompt`): `Promise`\\<`QueuedAction`\\>\n\nReplace this queued prompt's text before it dispatches. Returns this\nhandle for chaining; the edit endpoint answers 204, so `prompt` is\napplied locally rather than reread from a response body.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `prompt` | `string` |\n\n#### Returns\n\n`Promise`\\<`QueuedAction`\\>\n\n***\n\n### remove()\n\n> **remove**(): `Promise`\\<`void`\\>\n\nRemove this action from the queue before it dispatches.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### steer()\n\n> **steer**(): `Promise`\\<`void`\\>\n\nMove this action to the front and interrupt the current turn to run it next.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### from()\n\n> `static` **from**(`client`, `sessionId`, `dto`): `QueuedAction`\n\nWrap a queue entry already in hand (e.g. from `AgentSession.queue()`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `sessionId` | `string` |\n| `dto` | [`QueuedActionDto`](../../../../../generated/agent-harness/types.gen/type-aliases/QueuedActionDto.md) |\n\n#### Returns\n\n`QueuedAction`\n\n\n<!-- src/entities/agent-sessions/review/classes/ReviewItem.md -->\n# Class: ReviewItem\n\nAn item handle scopes edits and decisions to its persisted review.\n\n## Constructors\n\n### Constructor\n\n> **new ReviewItem**(`snapshot`, `actions`): `ReviewItem`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `snapshot` | [`ReviewItem`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItem.md) |\n| `actions` | \\{ `dismiss`: () => `Promise`\\<`void`\\>; `edit`: (`draft`) => `Promise`\\<`void`\\>; `submit`: () => `Promise`\\<`void`\\>; \\} |\n| `actions.dismiss` | () => `Promise`\\<`void`\\> |\n| `actions.edit` | (`draft`) => `Promise`\\<`void`\\> |\n| `actions.submit` | () => `Promise`\\<`void`\\> |\n\n#### Returns\n\n`ReviewItem`\n\n## Accessors\n\n### draft\n\n#### Get Signature\n\n> **get** **draft**(): `unknown`\n\n##### Returns\n\n`unknown`\n\n***\n\n### id\n\n#### Get Signature\n\n> **get** **id**(): `string`\n\n##### Returns\n\n`string`\n\n***\n\n### result\n\n#### Get Signature\n\n> **get** **result**(): `unknown`\n\n##### Returns\n\n`unknown`\n\n***\n\n### status\n\n#### Get Signature\n\n> **get** **status**(): [`ReviewItemStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md)\n\n##### Returns\n\n[`ReviewItemStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md)\n\n## Methods\n\n### dismiss()\n\n> **dismiss**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### edit()\n\n> **edit**(`draft`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `draft` | `unknown` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### submit()\n\n> **submit**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n\n<!-- src/entities/agent-sessions/review/classes/SessionReview.md -->\n# Class: SessionReview\n\nA persistent review remains actionable after the code execution ends.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Inherited from |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-kind\"></a> `kind` | `readonly` | () => `Promise`\\<[`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md)\\> | - |\n| <a id=\"property-title\"></a> `title` | `readonly` | () => `Promise`\\<`string`\\> | - |\n\n## Methods\n\n### dismissAll()\n\n> **dismissAll**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### items()\n\n> **items**(): `Promise`\\<[`ReviewItem`](ReviewItem.md)[]\\>\n\n#### Returns\n\n`Promise`\\<[`ReviewItem`](ReviewItem.md)[]\\>\n\n***\n\n### reference()\n\n> **reference**(): `Promise`\\<\\{ `id`: `string`; `kind`: [`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md); \\}\\>\n\nCompact reference for main()'s returned reviews array.\n\n#### Returns\n\n`Promise`\\<\\{ `id`: `string`; `kind`: [`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md); \\}\\>\n\n***\n\n### refresh()\n\n> **refresh**(): `Promise`\\<`SessionReview`\\>\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### submitAll()\n\n> **submitAll**(): `Promise`\\<`void`\\>\n\nSubmit the saved pending drafts. Never retries a conflict or ambiguous send.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `SessionReview`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`SessionReview`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `execution`, `input`): `Promise`\\<`SessionReview`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `execution` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n| `input` | [`CreateReviewOptions`](../type-aliases/CreateReviewOptions.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### createForSession()\n\n> `static` **createForSession**(`client`, `session`, `input`, `execution?`): `Promise`\\<`SessionReview`\\>\n\nPresent a review in a session without requiring a code execution.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `input` | [`CreateReviewOptions`](../type-aliases/CreateReviewOptions.md) |\n| `execution?` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `session`, `record`): `SessionReview`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `record` | [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md) |\n\n#### Returns\n\n`SessionReview`\n\n***\n\n### list()\n\n> `static` **list**(`client`, `execution`): `Promise`\\<`SessionReview`[]\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `execution` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`[]\\>\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/CreateReviewOptions.md -->\n# Type Alias: CreateReviewOptions\n\n> **CreateReviewOptions** = \\{ `drafts`: [`ReviewEmailDraft`](ReviewEmailDraft.md)[]; `kind`: `\"email\"`; `title`: `string`; \\} \\| \\{ `drafts`: [`ReviewCalendarDraft`](ReviewCalendarDraft.md)[]; `kind`: `\"calendar\"`; `title`: `string`; \\}\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/ReviewCalendarDraft.md -->\n# Type Alias: ReviewCalendarDraft\n\n> **ReviewCalendarDraft** = \\{ `addGoogleMeet?`: `boolean`; `addMacroCall?`: `boolean`; `attendees?`: \\{ `email`: `string`; `isOptional?`: `boolean`; \\}[]; `calendarId?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: `\"default\"` \\| `\"out_of_office\"`; `location?`: `string` \\| `null`; `outOfOffice?`: \\{ `autoDeclineMode?`: `\"decline_none\"` \\| `\"decline_all\"` \\| `\"decline_new_only\"`; `declineMessage?`: `string` \\| `null`; \\} \\| `null`; `recurrenceLines?`: `string`[]; `reminders?`: \\{ `overrides?`: \\{ `method`: `string`; `minutes`: `number`; \\}[]; `useDefault`: `boolean`; \\} \\| `null`; `time`: [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md); `title`: `string`; \\}\n\nCalendar drafts use the existing calendar composer and creation action.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-addgooglemeet\"></a> `addGoogleMeet?` | `boolean` |\n| <a id=\"property-addmacrocall\"></a> `addMacroCall?` | `boolean` |\n| <a id=\"property-attendees\"></a> `attendees?` | \\{ `email`: `string`; `isOptional?`: `boolean`; \\}[] |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` |\n| <a id=\"property-eventtype\"></a> `eventType?` | `\"default\"` \\| `\"out_of_office\"` |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | \\{ `autoDeclineMode?`: `\"decline_none\"` \\| `\"decline_all\"` \\| `\"decline_new_only\"`; `declineMessage?`: `string` \\| `null`; \\} \\| `null` |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] |\n| <a id=\"property-reminders\"></a> `reminders?` | \\{ `overrides?`: \\{ `method`: `string`; `minutes`: `number`; \\}[]; `useDefault`: `boolean`; \\} \\| `null` |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) |\n| <a id=\"property-title\"></a> `title` | `string` |\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/ReviewEmailDraft.md -->\n# Type Alias: ReviewEmailDraft\n\n> **ReviewEmailDraft** = \\{ `attachments?`: \\{ `documentId`: `string`; \\}[]; `bcc?`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; `body`: `string`; `cc?`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; `includeSignature?`: `boolean` \\| `null`; `replyingToId?`: `string` \\| `null`; `subject`: `string`; `to`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; \\}\n\nMarkdown is rendered by the ordinary email action; the UI can edit each draft.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments?` | \\{ `documentId`: `string`; \\}[] |\n| <a id=\"property-bcc\"></a> `bcc?` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n| <a id=\"property-body\"></a> `body` | `string` |\n| <a id=\"property-cc\"></a> `cc?` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n| <a id=\"property-includesignature\"></a> `includeSignature?` | `boolean` \\| `null` |\n| <a id=\"property-replyingtoid\"></a> `replyingToId?` | `string` \\| `null` |\n| <a id=\"property-subject\"></a> `subject` | `string` |\n| <a id=\"property-to\"></a> `to` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n\n\n<!-- src/entities/agent-sessions/tool-approval/classes/ToolApproval.md -->\n# Class: ToolApproval\n\nA permission request scoped to its originating agent session.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | Approval identity. |\n| <a id=\"property-session\"></a> `session` | `readonly` | [`AgentSession`](../../agent-session/classes/AgentSession.md) | Owning session. |\n\n## Methods\n\n### answer()\n\n> **answer**(`answer`): `Promise`\\<[`AnswerToolApprovalResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md)\\>\n\nAnswer the approval using the generated discriminated answer contract.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `answer` | [`ToolApprovalAnswerDto`](../../../../../generated/agent-harness/types.gen/type-aliases/ToolApprovalAnswerDto.md) |\n\n#### Returns\n\n`Promise`\\<[`AnswerToolApprovalResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `id`: `string`; `sessionId`: `string`; \\}\n\nSerialize scoped identity only.\n\n#### Returns\n\n\\{ `id`: `string`; `sessionId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `id` | `string` |\n| `sessionId` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `ToolApproval`\n\nConstruct a scoped approval handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`ToolApproval`\n"
+ "documentation": "# Macro SDK: agentSessions\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/agent-harness/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentAction.md -->\n# Type Alias: AgentAction\n\n> **AgentAction** = [`AgentPromptAction`](AgentPromptAction.md) & \\{ `type`: `\"prompt\"`; \\} \\| [`AgentSetModelAction`](AgentSetModelAction.md) & \\{ `type`: `\"setModel\"`; \\} \\| [`AgentSetConfigOptionAction`](AgentSetConfigOptionAction.md) & \\{ `type`: `\"setConfigOption\"`; \\} \\| \\{ `type`: `\"compact\"`; \\} \\| \\{ `type`: `\"stop\"`; \\} \\| [`AgentRespondElicitationAction`](AgentRespondElicitationAction.md) & \\{ `type`: `\"respondElicitation\"`; \\} \\| [`AgentPermissionAction`](AgentPermissionAction.md) & \\{ `type`: `\"respondToPermission\"`; \\}\n\nOne thing a caller wants an agent to do.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentActionId.md -->\n# Type Alias: AgentActionId\n\n> **AgentActionId** = `string`\n\nIdentifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationDto.md -->\n# Type Alias: AgentConversationDto\n\n> **AgentConversationDto** = \\{ `available`: `boolean`; `avatarUrl?`: `string` \\| `null`; `botId`: `string`; `channelId`: `string`; `name`: `string`; `sessions`: [`AgentConversationSessionDto`](AgentConversationSessionDto.md)[]; `settingsChanged`: `boolean`; `turns`: [`AgentConversationTurnDto`](AgentConversationTurnDto.md)[]; \\}\n\nAn agent's conversation in a channel, as the person it is with sees it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-available\"></a> `available` | `boolean` | Whether the caller may currently send a new prompt. |\n| <a id=\"property-avatarurl\"></a> `avatarUrl?` | `string` \\| `null` | Optional persona avatar. |\n| <a id=\"property-botid\"></a> `botId` | `string` | Persona id (without the bot principal prefix). |\n| <a id=\"property-channelid\"></a> `channelId` | `string` | The channel containing the visible transcript. |\n| <a id=\"property-name\"></a> `name` | `string` | Persona's historical display name. |\n| <a id=\"property-sessions\"></a> `sessions` | [`AgentConversationSessionDto`](AgentConversationSessionDto.md)[] | The sessions the conversation has run on, oldest first. |\n| <a id=\"property-settingschanged\"></a> `settingsChanged` | `boolean` | Whether new persona settings are available to adopt explicitly. |\n| <a id=\"property-turns\"></a> `turns` | [`AgentConversationTurnDto`](AgentConversationTurnDto.md)[] | Persistent state of each accepted message and its current attempt. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationSessionDto.md -->\n# Type Alias: AgentConversationSessionDto\n\n> **AgentConversationSessionDto** = \\{ `createdAt`: `string`; `isCurrent`: `boolean`; `sessionId`: `string`; \\}\n\nOne session a conversation has run on; every channel message stays visible.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the session began. |\n| <a id=\"property-iscurrent\"></a> `isCurrent` | `boolean` | Whether this is the current agent context. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Session whose controls and live events belong to this context. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentConversationTurnDto.md -->\n# Type Alias: AgentConversationTurnDto\n\n> **AgentConversationTurnDto** = \\{ `actionId`: `string`; `createdAt`: `string`; `replyMessageId?`: `string` \\| `null`; `retryable`: `boolean`; `sessionId`: `string`; `sourceMessageId`: `string`; `state`: [`ConversationTurnState`](ConversationTurnState.md); \\}\n\nExecution status without exposing the persona prompt or stored credentials.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | `string` | Current runtime attempt identity. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the source message was first accepted. |\n| <a id=\"property-replymessageid\"></a> `replyMessageId?` | `string` \\| `null` | The associated agent reply, if it has been posted. |\n| <a id=\"property-retryable\"></a> `retryable` | `boolean` | Whether Retry would be accepted now. A failed attempt is not retryable until its reply says how it ended. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Session carrying this turn. |\n| <a id=\"property-sourcemessageid\"></a> `sourceMessageId` | `string` | The user's message in the channel timeline. |\n| <a id=\"property-state\"></a> `state` | [`ConversationTurnState`](ConversationTurnState.md) | Durable execution state. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentPermissionAction.md -->\n# Type Alias: AgentPermissionAction\n\n> **AgentPermissionAction** = \\{ `answer`: [`PermissionAnswer`](PermissionAnswer.md); `requestId`: `unknown`; \\}\n\nA user's answer to the agent's `session/request_permission`.\n\nUnlike every other action this is not a new request but the reply to one\nthe agent made, so it carries the agent's own request id rather than\nreceiving a server-minted one.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-answer\"></a> `answer` | [`PermissionAnswer`](PermissionAnswer.md) | What the user decided. |\n| <a id=\"property-requestid\"></a> `requestId` | `unknown` | The agent's JSON-RPC request id, echoed verbatim from the folded permission part. A string or a number on the wire; agents mint both, and `7` does not answer `\"7\"`. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentPromptAction.md -->\n# Type Alias: AgentPromptAction\n\n> **AgentPromptAction** = \\{ `attachments?`: [`PromptAttachment`](PromptAttachment.md)[]; `prompt`: `string`; \\}\n\nAsk the agent to work on something.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments?` | [`PromptAttachment`](PromptAttachment.md)[] | Files the prompt refers to, in the order the user attached them. Delivered after the text as one `resource_link` block each. |\n| <a id=\"property-prompt\"></a> `prompt` | `string` | What to tell the agent. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentRespondElicitationAction.md -->\n# Type Alias: AgentRespondElicitationAction\n\n> **AgentRespondElicitationAction** = [`ElicitationAnswer`](ElicitationAnswer.md) & \\{ `requestId`: [`ElicitationRequestId`](ElicitationRequestId.md); \\}\n\nAnswer an elicitation the agent is waiting on.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `requestId` | [`ElicitationRequestId`](ElicitationRequestId.md) | The agent's `elicitation/create` request id - not an [`AgentActionId`], because the agent minted it. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md -->\n# Type Alias: AgentSessionChangesResponse\n\n> **AgentSessionChangesResponse** = \\{ `attempt?`: `null` \\| [`CaptureAttemptDto`](CaptureAttemptDto.md); `capturing`: `boolean`; `changeset?`: `null` \\| [`ChangesetDto`](ChangesetDto.md); \\}\n\nResponse body for `GET /agent-sessions/{session_id}/changes`.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attempt\"></a> `attempt?` | `null` \\| [`CaptureAttemptDto`](CaptureAttemptDto.md) | - |\n| <a id=\"property-capturing\"></a> `capturing` | `boolean` | A capture is running right now. |\n| <a id=\"property-changeset\"></a> `changeset?` | `null` \\| [`ChangesetDto`](ChangesetDto.md) | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionLogEntryDto.md -->\n# Type Alias: AgentSessionLogEntryDto\n\n> **AgentSessionLogEntryDto** = [`LogFrameDto`](LogFrameDto.md) & \\{ `createdAt`: `string`; `id`: `string`; `userId?`: `string` \\| `null`; \\}\n\nOne entry of a session's protocol log.\n\nSerializes as `{\"userId\": ..., \"direction\": ..., \"content\": ...}` - the\nframe's own two fields, flattened in beside the attribution, which is the\nsame shape a recorded session's JSONL carries. A reader can deserialize the\n`direction`/`content` pair straight back into the fold's own log type\nrather than through a transport vocabulary of its own.\n\n`agentSessionId` is not repeated per entry: every entry in a response\nbelongs to the session named once at the top.\n\n`Deserialize` is for the wire-contract tests only - nothing server-side\ndecodes its own response type.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | When the log recorded the frame. The frame itself carries no time, so this comes from the log row. It is what a reader has to order these against anything else it is showing beside them - the fold derives an order among the messages of one session and nothing more. |\n| `id` | `string` | Durable transport row identity; together with `createdAt`, its order cursor. |\n| `userId?` | `string` \\| `null` | The user whose action produced the frame, absent when no user did. Only prompts carry one, and only when the frame was attributed at the time - a replayed or recorded session's are anonymous. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md -->\n# Type Alias: AgentSessionLogResponse\n\n> **AgentSessionLogResponse** = \\{ `bot`: [`SessionBot`](SessionBot.md); `entries`: [`AgentSessionLogEntryDto`](AgentSessionLogEntryDto.md)[]; \\}\n\nResponse body for one session's raw protocol log.\n\nA wrapper rather than a bare array so that anything which is about the\nresponse rather than about a frame has somewhere to go later without\nbreaking every client.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bot\"></a> `bot` | [`SessionBot`](SessionBot.md) | The agent whose messages the log derives. Here because a client renders those messages and cannot otherwise work out who sent them: the sender of an agent message is this session's bot, and nothing else names it. |\n| <a id=\"property-entries\"></a> `entries` | [`AgentSessionLogEntryDto`](AgentSessionLogEntryDto.md)[] | Effective history in ascending `(createdAt, id)` order. The first row is the inclusive history boundary cursor: buffered rows before it are obsolete. Reconcile snapshot overlap by row ID, never content. An empty history has no boundary or overlapping rows. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md -->\n# Type Alias: AgentSessionResponse\n\n> **AgentSessionResponse** = \\{ `acpSessionId?`: `string` \\| `null`; `botId`: `string`; `canEdit`: `boolean`; `createdAt`: `string`; `external?`: `null` \\| [`ExternalSessionResponse`](ExternalSessionResponse.md); `harness`: `string`; `id`: `string`; `instructions?`: `string` \\| `null`; `isArchived`: `boolean`; `model`: `string`; `modifiedAt`: `string`; `name`: `string`; `originatingMessageId?`: `string` \\| `null`; `ownerId`: `string`; `pullRequestUrl?`: `string` \\| `null`; `repoUrl?`: `string` \\| `null`; `sandboxSize`: [`SandboxSize`](SandboxSize.md); `status`: [`SessionStatusDto`](SessionStatusDto.md); `taskId?`: `string` \\| `null`; `threadChannelId?`: `string` \\| `null`; `threadId?`: `string` \\| `null`; `threadParent?`: `null` \\| [`MessageParent`](MessageParent.md); `workspace`: `string`; \\}\n\nResponse body describing an agent session.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-acpsessionid\"></a> `acpSessionId?` | `string` \\| `null` | The ACP session id, if one exists. |\n| <a id=\"property-botid\"></a> `botId` | `string` | The bot running the agent. |\n| <a id=\"property-canedit\"></a> `canEdit` | `boolean` | Whether the caller may drive the session - prompt it, answer its questions, stop it - rather than only watch. Edit access; the creator owns the session, so a create response always says so. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the session was created. |\n| <a id=\"property-external\"></a> `external?` | `null` \\| [`ExternalSessionResponse`](ExternalSessionResponse.md) | - |\n| <a id=\"property-harness\"></a> `harness` | `string` | Harness slug. |\n| <a id=\"property-id\"></a> `id` | `string` | The session id. |\n| <a id=\"property-instructions\"></a> `instructions?` | `string` \\| `null` | Instructions the session's runtime works under, when any were stated at creation. Absent otherwise, so existing payloads are unchanged. |\n| <a id=\"property-isarchived\"></a> `isArchived` | `boolean` | Whether the session is archived and read-only. |\n| <a id=\"property-model\"></a> `model` | `string` | Model slug. |\n| <a id=\"property-modifiedat\"></a> `modifiedAt` | `string` | When the session was last modified. |\n| <a id=\"property-name\"></a> `name` | `string` | User-facing session name. |\n| <a id=\"property-originatingmessageid\"></a> `originatingMessageId?` | `string` \\| `null` | The exact message that invoked the bot, if any. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | The user who created and owns the session. |\n| <a id=\"property-pullrequesturl\"></a> `pullRequestUrl?` | `string` \\| `null` | The session's linked pull request. |\n| <a id=\"property-repourl\"></a> `repoUrl?` | `string` \\| `null` | The repository the session works with, when one was stated. |\n| <a id=\"property-sandboxsize\"></a> `sandboxSize` | [`SandboxSize`](SandboxSize.md) | Compute tier of the managed sandbox. |\n| <a id=\"property-status\"></a> `status` | [`SessionStatusDto`](SessionStatusDto.md) | The session's status. |\n| <a id=\"property-taskid\"></a> `taskId?` | `string` \\| `null` | The Macro task the session was linked to. |\n| <a id=\"property-threadchannelid\"></a> `threadChannelId?` | `string` \\| `null` | The channel `thread_id` lives in, when the session was spawned from a channel thread. Derived from `thread_parent`. |\n| <a id=\"property-threadid\"></a> `threadId?` | `string` \\| `null` | The root message of the thread the session was created from, if any. |\n| <a id=\"property-threadparent\"></a> `threadParent?` | `null` \\| [`MessageParent`](MessageParent.md) | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSetConfigOptionAction.md -->\n# Type Alias: AgentSetConfigOptionAction\n\n> **AgentSetConfigOptionAction** = \\{ `configId`: `string`; `value`: `string`; \\}\n\nAsk the agent to change one advertised select-style session setting.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-configid\"></a> `configId` | `string` | Opaque ACP config id advertised by the agent. |\n| <a id=\"property-value\"></a> `value` | `string` | Opaque select value advertised for that config option. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AgentSetModelAction.md -->\n# Type Alias: AgentSetModelAction\n\n> **AgentSetModelAction** = \\{ `model`: `string`; \\}\n\nAsk the agent to run on a different model from here on.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-model\"></a> `model` | `string` | The model slug the agent should switch to. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md -->\n# Type Alias: AnswerToolApprovalResponse\n\n> **AnswerToolApprovalResponse** = \\{ `status`: [`ToolApprovalStatusDto`](ToolApprovalStatusDto.md); \\}\n\nResponse body for answering a held tool call.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-status\"></a> `status` | [`ToolApprovalStatusDto`](ToolApprovalStatusDto.md) | Where the call stands now. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/BotId.md -->\n# Type Alias: BotId\n\n> **BotId** = `string`\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CaptureAttemptDto.md -->\n# Type Alias: CaptureAttemptDto\n\n> **CaptureAttemptDto** = \\{ `error?`: `string` \\| `null`; `finishedAt?`: `string` \\| `null`; `outcome?`: `null` \\| [`CaptureOutcomeDto`](CaptureOutcomeDto.md); `startedAt`: `string`; \\}\n\nThe latest capture attempt.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Why it did not capture, in a sentence the user can read. |\n| <a id=\"property-finishedat\"></a> `finishedAt?` | `string` \\| `null` | When it ended; absent while it runs. |\n| <a id=\"property-outcome\"></a> `outcome?` | `null` \\| [`CaptureOutcomeDto`](CaptureOutcomeDto.md) | - |\n| <a id=\"property-startedat\"></a> `startedAt` | `string` | When it started. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CaptureOutcomeDto.md -->\n# Type Alias: CaptureOutcomeDto\n\n> **CaptureOutcomeDto** = `\"captured\"` \\| `\"not_ready\"` \\| `\"failed\"`\n\nHow the latest capture attempt ended, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangedFileDto.md -->\n# Type Alias: ChangedFileDto\n\n> **ChangedFileDto** = \\{ `additions`: `number`; `binary`: `boolean`; `deletions`: `number`; `kind`: [`FileChangeKindDto`](FileChangeKindDto.md); `patchOmitted`: `boolean`; `path`: `string`; `previousPath?`: `string` \\| `null`; \\}\n\nOne changed file.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions` | `number` | Lines added. |\n| <a id=\"property-binary\"></a> `binary` | `boolean` | The diff carries no text for this file. |\n| <a id=\"property-deletions\"></a> `deletions` | `number` | Lines removed. |\n| <a id=\"property-kind\"></a> `kind` | [`FileChangeKindDto`](FileChangeKindDto.md) | What happened to the file. |\n| <a id=\"property-patchomitted\"></a> `patchOmitted` | `boolean` | The file's hunks were left out of the patch to fit the size budget. |\n| <a id=\"property-path\"></a> `path` | `string` | The file's path after the change, or before it for a deletion. |\n| <a id=\"property-previouspath\"></a> `previousPath?` | `string` \\| `null` | Where a renamed file came from. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangesetDto.md -->\n# Type Alias: ChangesetDto\n\n> **ChangesetDto** = \\{ `additions`: `number`; `base`: [`GitRefDto`](GitRefDto.md); `capturedAt`: `string`; `deletions`: `number`; `files`: [`ChangedFileDto`](ChangedFileDto.md)[]; `head`: [`GitRefDto`](GitRefDto.md); `id`: `string`; `patchBytes`: `number`; `repository?`: `string` \\| `null`; `source`: [`ChangesetSourceDto`](ChangesetSourceDto.md); `truncated`: `boolean`; \\}\n\nOne changeset: the files a patch touches and what happened to each.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions` | `number` | Lines added across all files. |\n| <a id=\"property-base\"></a> `base` | [`GitRefDto`](GitRefDto.md) | The side the work started from. |\n| <a id=\"property-capturedat\"></a> `capturedAt` | `string` | When the diff was taken. |\n| <a id=\"property-deletions\"></a> `deletions` | `number` | Lines removed across all files. |\n| <a id=\"property-files\"></a> `files` | [`ChangedFileDto`](ChangedFileDto.md)[] | Every changed file, in patch order. |\n| <a id=\"property-head\"></a> `head` | [`GitRefDto`](GitRefDto.md) | The side carrying the work. |\n| <a id=\"property-id\"></a> `id` | `string` | The changeset's id; a different id means different changes. |\n| <a id=\"property-patchbytes\"></a> `patchBytes` | `number` | Size of the patch the matching patch route serves; zero when nothing changed. |\n| <a id=\"property-repository\"></a> `repository?` | `string` \\| `null` | `https://github.com/owner/name`, when known. |\n| <a id=\"property-source\"></a> `source` | [`ChangesetSourceDto`](ChangesetSourceDto.md) | Where the diff was read from. |\n| <a id=\"property-truncated\"></a> `truncated` | `boolean` | Some files' hunks were left out of the patch. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChangesetSourceDto.md -->\n# Type Alias: ChangesetSourceDto\n\n> **ChangesetSourceDto** = `\"github_pull_request\"`\n\nThe source of a changeset's diff, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md -->\n# Type Alias: CodingPreferencesBody\n\n> **CodingPreferencesBody** = \\{ `createTasks`: `boolean`; `openPullRequests`: `boolean`; \\}\n\nRequest or response body for the caller's coding preferences.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createtasks\"></a> `createTasks` | `boolean` | Whether new coding sessions research prior work and link a Macro task. |\n| <a id=\"property-openpullrequests\"></a> `openPullRequests` | `boolean` | Whether new coding sessions deliver their work as a pull request. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ControlResponse.md -->\n# Type Alias: ControlResponse\n\n> **ControlResponse** = \\{ `actionId`: [`AgentActionId`](AgentActionId.md); `status`: [`ControlStatusDto`](ControlStatusDto.md); \\}\n\nResponse body for a control operation.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | [`AgentActionId`](AgentActionId.md) | Matches `requestId` on the folded message this action derives once it dispatches, and names the queue entry until then. The caller's own `actionId` when it supplied one; a freshly minted id otherwise. |\n| <a id=\"property-status\"></a> `status` | [`ControlStatusDto`](ControlStatusDto.md) | Whether the action went out or waits in the queue. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ControlStatusDto.md -->\n# Type Alias: ControlStatusDto\n\n> **ControlStatusDto** = `\"sent\"` \\| `\"queued\"`\n\nWhat accepting a control operation did with it, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ConversationTurnState.md -->\n# Type Alias: ConversationTurnState\n\n> **ConversationTurnState** = `\"queued\"` \\| `\"running\"` \\| `\"succeeded\"` \\| `\"failed\"` \\| `\"stopped\"` \\| `\"interrupted\"`\n\nThe state of one source message, retained after completion for deduplication.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/DocumentId.md -->\n# Type Alias: DocumentId\n\n> **DocumentId** = `string`\n\nA validated document identifier. Historical document ids need not be UUIDs.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationAnswer.md -->\n# Type Alias: ElicitationAnswer\n\n> **ElicitationAnswer** = \\{ `action`: `\"accept\"`; `content?`: \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null`; \\} \\| \\{ `action`: `\"decline\"`; \\} \\| \\{ `action`: `\"cancel\"`; \\}\n\nWhat the user decided about an elicitation. Mirrors ACP's three actions;\nthere is no `Other` because we never originate an action we do not know.\n\n## Union Members\n\n### Type Literal\n\n\\{ `action`: `\"accept\"`; `content?`: \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `action` | `\"accept\"` | - |\n| `content?` | \\{\\[`key`: `string`\\]: [`ElicitationContentValue`](ElicitationContentValue.md); \\} \\| `null` | Form: the submitted values keyed by property. URL: omitted. |\n\n***\n\n### Type Literal\n\n\\{ `action`: `\"decline\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `action`: `\"cancel\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationContentValue.md -->\n# Type Alias: ElicitationContentValue\n\n> **ElicitationContentValue** = `string` \\| `boolean` \\| `number` \\| `number` \\| `string`[]\n\nA value ACP accepts in an elicitation answer.\n\nMirrors ACP's `ElicitationContentValue` so that the contract a caller\nanswers against is the closed union ACP will accept, rather than arbitrary\nJSON narrowed on the way out. An object, a null, or a mixed array is\nrefused when the request is deserialized - where the caller learns of it -\ninstead of at send time, when the elicitation slot has already been\nreleased.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ElicitationRequestId.md -->\n# Type Alias: ElicitationRequestId\n\n> **ElicitationRequestId** = `number` \\| `string`\n\nThe JSON-RPC id of an agent's `elicitation/create` request, carried whole\nso the answer echoes exactly what the agent sent.\n\nAgents pick these, not us: Claude Code counts from `0`, others use\nstrings. `null` is not a legal id for a request that expects a response,\nso it is not representable here.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionActivity.md -->\n# Type Alias: ExecutionActivity\n\n> **ExecutionActivity** = \\{ `id`: `number`; `label`: `string`; `status`: [`RecordedCallStatus`](RecordedCallStatus.md); \\}\n\nA bounded SDK operation observed during execution; not an authorization or write receipt.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` | Request identity within the execution. |\n| <a id=\"property-label\"></a> `label` | `string` | Server-selected label from the generated operation catalog. |\n| <a id=\"property-status\"></a> `status` | [`RecordedCallStatus`](RecordedCallStatus.md) | Observed request state; unfinished operations have unknown outcomes. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionId.md -->\n# Type Alias: ExecutionId\n\n> **ExecutionId** = `string`\n\nCaller-selected UUID persisted in tool input before execution begins.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md -->\n# Type Alias: ExecutionRecord\n\n> **ExecutionRecord** = \\{ `activity?`: [`ExecutionActivity`](ExecutionActivity.md)[]; `activityTruncated?`: `boolean`; `calls`: [`RecordedToolCall`](RecordedToolCall.md)[]; `error?`: `string` \\| `null`; `executionId`: [`ExecutionId`](ExecutionId.md); `result?`: `unknown`; `source`: `string`; `status`: [`ExecutionStatus`](ExecutionStatus.md); \\}\n\nDurable source and final outcome, with historical bridge calls when present.\nThe full journal is not included in the model's tool result.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-activity\"></a> `activity?` | [`ExecutionActivity`](ExecutionActivity.md)[] | Advisory SDK operation activity, without arguments or response contents. |\n| <a id=\"property-activitytruncated\"></a> `activityTruncated?` | `boolean` | Additional request activity was omitted at the bounded observation limit. |\n| <a id=\"property-calls\"></a> `calls` | [`RecordedToolCall`](RecordedToolCall.md)[] | Historical bridge calls. Direct HTTP executions leave this empty. |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Safe execution failure text. |\n| <a id=\"property-executionid\"></a> `executionId` | [`ExecutionId`](ExecutionId.md) | Execution identity. |\n| <a id=\"property-result\"></a> `result?` | `unknown` | JSON returned by the program, if successful. |\n| <a id=\"property-source\"></a> `source` | `string` | The submitted JavaScript module. |\n| <a id=\"property-status\"></a> `status` | [`ExecutionStatus`](ExecutionStatus.md) | Overall execution state. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExecutionStatus.md -->\n# Type Alias: ExecutionStatus\n\n> **ExecutionStatus** = `\"running\"` \\| `\"succeeded\"` \\| `\"failed\"` \\| `\"cancelled\"` \\| `\"timed_out\"`\n\nThe recorded outcome of a program.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ExternalSessionResponse.md -->\n# Type Alias: ExternalSessionResponse\n\n> **ExternalSessionResponse** = \\{ `name?`: `string` \\| `null`; `provider`: `string`; `url?`: `string` \\| `null`; \\}\n\nThe provider-side identity of an externally-served session.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The provider's display name for the agent, when it reported one. |\n| <a id=\"property-provider\"></a> `provider` | `string` | Which provider serves the session, e.g. `cursor`. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The agent's page on the provider's site, for a client to link out to. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/FileChangeKindDto.md -->\n# Type Alias: FileChangeKindDto\n\n> **FileChangeKindDto** = `\"added\"` \\| `\"modified\"` \\| `\"deleted\"` \\| `\"renamed\"`\n\nWhat happened to a file, on the wire.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/GitRefDto.md -->\n# Type Alias: GitRefDto\n\n> **GitRefDto** = \\{ `name?`: `string` \\| `null`; `sha?`: `string` \\| `null`; \\}\n\nOne end of the compared range.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The branch name, when known. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The commit, when known. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LogDirectionDto.md -->\n# Type Alias: LogDirectionDto\n\n> **LogDirectionDto** = `\"to_server\"` \\| `\"to_runtime\"`\n\nWhich way a logged frame travelled, mirroring [`Message`]'s discriminant.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/LogFrameDto.md -->\n# Type Alias: LogFrameDto\n\n> **LogFrameDto** = \\{ `content`: \\{\\[`key`: `string`\\]: `unknown`; \\}; `direction`: [`LogDirectionDto`](LogDirectionDto.md); \\}\n\nThe two fields [`AgentSessionLogEntryDto`] flattens in.\n\nSchema only. Nothing constructs one: the entry serializes through\n[`Message`], and this exists so the generated clients see `direction` and\n`content` as named fields instead of an open map. A hand-built copy could\ndrift from the fold's wire format, and the point of the endpoint is that it\ncannot - so this describes that format without being able to produce it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-content\"></a> `content` | \\{\\[`key`: `string`\\]: `unknown`; \\} | The protocol envelope, verbatim. Opaque here: it is Agent Runtime Protocol, whose shape belongs to the fold rather than this endpoint. |\n| <a id=\"property-direction\"></a> `direction` | [`LogDirectionDto`](LogDirectionDto.md) | Which way the frame travelled. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `id`: `string`; `type`: `\"channel\"`; \\} \\| \\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\} \\| \\{ `id`: `string`; `type`: `\"initiative\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_company\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_contact\"`; \\} \\| \\{ `id`: `string`; `type`: `\"call\"`; \\}\n\nThe entity whose permissions and lifecycle govern a message.\n\n## Union Members\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A channel, including direct messages. |\n| `type` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | [`DocumentId`](DocumentId.md) | A document, including tasks and PDFs. |\n| `type` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | An initiative, presented as a project in the application. |\n| `type` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_company\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM company. |\n| `type` | `\"crm_company\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_contact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM contact. |\n| `type` | `\"crm_contact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A video call and its persistent chat thread. |\n| `type` | `\"call\"` | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PermissionAnswer.md -->\n# Type Alias: PermissionAnswer\n\n> **PermissionAnswer** = \\{ `kind`: `\"selected\"`; `optionId`: `string`; \\} \\| \\{ `kind`: `\"cancelled\"`; \\}\n\nThe decision carried by an [`AgentPermissionAction`].\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"selected\"`; `optionId`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `kind` | `\"selected\"` | - |\n| `optionId` | `string` | The chosen option's id, as the agent listed it. |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"cancelled\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PromptAttachment.md -->\n# Type Alias: PromptAttachment\n\n> **PromptAttachment** = \\{ `mimeType?`: `string` \\| `null`; `name`: `string`; `size?`: `number` \\| `null`; `uri`: `string`; \\}\n\nA file the prompt refers to, by where the agent can fetch it.\n\nMirrors ACP's `resource_link` content block, which every agent must\naccept: bytes never ride the prompt, only a URI (a static file service URL\nin practice) with enough metadata for a client to render a chip and for\nthe agent to decide whether to fetch it. Keeping the wire shape ACP-native\nmeans the harness translates without resolving anything, and the fold\nreads the same fields back off the logged frame.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-mimetype\"></a> `mimeType?` | `string` \\| `null` | The file's media type, when known. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name, typically the original file name. |\n| <a id=\"property-size\"></a> `size?` | `number` \\| `null` | Size in bytes, when known. |\n| <a id=\"property-uri\"></a> `uri` | `string` | Where the agent can fetch the file. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md -->\n# Type Alias: PullRequestLinkSource\n\n> **PullRequestLinkSource** = `\"agent\"` \\| `\"user\"`\n\nWho associated a pull request with a session.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/QueuedActionDto.md -->\n# Type Alias: QueuedActionDto\n\n> **QueuedActionDto** = \\{ `actionId`: [`AgentActionId`](AgentActionId.md); `actorUserId?`: `string` \\| `null`; `attachments?`: [`PromptAttachment`](PromptAttachment.md)[]; `createdAt`: `string`; `kind`: `string`; `prompt?`: `string` \\| `null`; \\}\n\nOne action waiting in a session's queue.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-actionid\"></a> `actionId` | [`AgentActionId`](AgentActionId.md) | The id the action was accepted under. |\n| <a id=\"property-actoruserid\"></a> `actorUserId?` | `string` \\| `null` | The user who queued it, absent when a bot acted on nobody's behalf. |\n| <a id=\"property-attachments\"></a> `attachments?` | [`PromptAttachment`](PromptAttachment.md)[] | Files the prompt refers to, for prompts only. Kept through an edit, which replaces the text alone. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When it was accepted. |\n| <a id=\"property-kind\"></a> `kind` | `string` | What kind of action waits - `prompt` or `compact`; only turn-occupying actions are ever queued. |\n| <a id=\"property-prompt\"></a> `prompt?` | `string` \\| `null` | The prompt's raw text, present for prompts only. What an edit replaces. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/RecordedCallStatus.md -->\n# Type Alias: RecordedCallStatus\n\n> **RecordedCallStatus** = `\"running\"` \\| `\"completed\"` \\| `\"failed\"` \\| `\"unknown\"`\n\nA dispatch result; unfinished work is never reported as success.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/RecordedToolCall.md -->\n# Type Alias: RecordedToolCall\n\n> **RecordedToolCall** = \\{ `error?`: `string` \\| `null`; `id`: `string`; `input`: `unknown`; `name`: `string`; `output?`: `unknown`; `outputOmitted`: `boolean`; `status`: [`RecordedCallStatus`](RecordedCallStatus.md); \\}\n\nA real inner call, recorded by trusted dispatch for the existing renderers.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Safe tool failure, if one was returned. |\n| <a id=\"property-id\"></a> `id` | `string` | Stable, execution-scoped component identity. |\n| <a id=\"property-input\"></a> `input` | `unknown` | Arguments passed to the actual tool. |\n| <a id=\"property-name\"></a> `name` | `string` | Canonical Macro tool name from the allowlisted registry. |\n| <a id=\"property-output\"></a> `output?` | `unknown` | Original tool output, retained independently of the program's return value. |\n| <a id=\"property-outputomitted\"></a> `outputOmitted` | `boolean` | Whether the response was omitted to keep the durable journal bounded. |\n| <a id=\"property-status\"></a> `status` | [`RecordedCallStatus`](RecordedCallStatus.md) | A started call that never replied has an unknown side-effect outcome. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewId.md -->\n# Type Alias: ReviewId\n\n> **ReviewId** = `string`\n\nPersisted review identity.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewItem.md -->\n# Type Alias: ReviewItem\n\n> **ReviewItem** = \\{ `draft`: `unknown`; `error?`: `string` \\| `null`; `id`: `string`; `result?`: `unknown`; `status`: [`ReviewItemStatus`](ReviewItemStatus.md); \\}\n\nOne editable item and its durable outcome.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-draft\"></a> `draft` | `unknown` | Validated arguments for the existing composer/action. |\n| <a id=\"property-error\"></a> `error?` | `string` \\| `null` | Failure or uncertainty description. |\n| <a id=\"property-id\"></a> `id` | `string` | Stable item identity across stack navigation and edits. |\n| <a id=\"property-result\"></a> `result?` | `unknown` | Actual backend response, never a model assertion. |\n| <a id=\"property-status\"></a> `status` | [`ReviewItemStatus`](ReviewItemStatus.md) | Current outcome. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md -->\n# Type Alias: ReviewItemStatus\n\n> **ReviewItemStatus** = `\"pending\"` \\| `\"submitting\"` \\| `\"completed\"` \\| `\"dismissed\"` \\| `\"unknown\"`\n\nA review item never retries an ambiguous external result automatically.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewKind.md -->\n# Type Alias: ReviewKind\n\n> **ReviewKind** = `\"email\"` \\| `\"calendar\"`\n\nThe component and action used to finish a review.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ReviewRecord.md -->\n# Type Alias: ReviewRecord\n\n> **ReviewRecord** = \\{ `executionId?`: `null` \\| [`ExecutionId`](ExecutionId.md); `id`: [`ReviewId`](ReviewId.md); `items`: [`ReviewItem`](ReviewItem.md)[]; `kind`: [`ReviewKind`](ReviewKind.md); `notificationAttemptAt?`: `number` \\| `null`; `notificationId?`: `string` \\| `null`; `presentedAt?`: `number` \\| `null`; `revision`: `number`; `sessionId`: `string`; `title`: `string`; `updatedAt`: `number`; \\}\n\nFull UI record, fetched outside the model context.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-executionid\"></a> `executionId?` | `null` \\| [`ExecutionId`](ExecutionId.md) | - |\n| <a id=\"property-id\"></a> `id` | [`ReviewId`](ReviewId.md) | Review identity. |\n| <a id=\"property-items\"></a> `items` | [`ReviewItem`](ReviewItem.md)[] | Drafts and per-item outcomes. |\n| <a id=\"property-kind\"></a> `kind` | [`ReviewKind`](ReviewKind.md) | Component kind. |\n| <a id=\"property-notificationattemptat\"></a> `notificationAttemptAt?` | `number` \\| `null` | Most recent delivery claim, allowing retry after a replica stops. |\n| <a id=\"property-notificationid\"></a> `notificationId?` | `string` \\| `null` | Stable queued-action identity until the outcome has reached the session. A failed notification may be retried without repeating external actions. |\n| <a id=\"property-presentedat\"></a> `presentedAt?` | `number` \\| `null` | Durable presentation acknowledgment, separate from user decisions. |\n| <a id=\"property-revision\"></a> `revision` | `number` | Compare-and-swap revision for edits and submissions. |\n| <a id=\"property-sessionid\"></a> `sessionId` | `string` | Owning session. |\n| <a id=\"property-title\"></a> `title` | `string` | Stack label. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `number` | Milliseconds since epoch of the last state change. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SandboxSize.md -->\n# Type Alias: SandboxSize\n\n> **SandboxSize** = `\"small\"` \\| `\"default\"` \\| `\"large\"`\n\nNamed compute tier for a managed sandbox.\n\nThe API and database store the name. CPU, RAM, and disk live in\n`crates/agent_harness/sandbox_sizes.json`.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SessionBot.md -->\n# Type Alias: SessionBot\n\n> **SessionBot** = \\{ `avatarUrl?`: `string` \\| `null`; `handle`: `string`; `id`: [`BotId`](BotId.md); `name`: `string`; \\}\n\nThe agent behind a session, as much of it as rendering a message needs.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatarurl\"></a> `avatarUrl?` | `string` \\| `null` | Avatar, when it has one. |\n| <a id=\"property-handle\"></a> `handle` | `string` | Stable `@` handle, without a leading `@`. |\n| <a id=\"property-id\"></a> `id` | [`BotId`](BotId.md) | The bot's id. A message it sent has `\"bot\\|{id}\"` as its sender. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name. |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SessionStatusDto.md -->\n# Type Alias: SessionStatusDto\n\n> **SessionStatusDto** = \\{ `kind`: `\"no_messages\"`; \\} \\| \\{ `event`: `string`; `kind`: `\"event\"`; \\} \\| \\{ `kind`: `\"disconnected\"`; \\}\n\nTransport representation of a session's status, mirroring\n[`SessionStatus`].\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"no_messages\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `event`: `string`; `kind`: `\"event\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `event` | `string` | The wire name of the system event, e.g. `acp_ready`. |\n| `kind` | `\"event\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `kind`: `\"disconnected\"`; \\}\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ToolApprovalAnswerDto.md -->\n# Type Alias: ToolApprovalAnswerDto\n\n> **ToolApprovalAnswerDto** = `\"approve\"` \\| `\"approve_and_remember\"` \\| `\"deny\"` \\| `\"cancel\"`\n\nHow a person answers a held tool call.\n\n\n<!-- generated/agent-harness/types.gen/type-aliases/ToolApprovalStatusDto.md -->\n# Type Alias: ToolApprovalStatusDto\n\n> **ToolApprovalStatusDto** = `\"pending\"` \\| `\"approved\"` \\| `\"denied\"` \\| `\"cancelled\"` \\| `\"expired\"`\n\nWhere a held tool call stands once answered.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- src/entities/agent-sessions/agent-session/classes/AgentSession.md -->\n# Class: AgentSession\n\nA managed or externally hosted coding-agent session.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | Access requests and direct user grants. | - |\n| <a id=\"property-codeexecutions\"></a> `codeExecutions` | `readonly` | \\{ `byId`: (`id`) => [`CodeExecution`](../../code-execution/classes/CodeExecution.md); \\} | Saved code executions scoped to this session. Handle construction makes no request. | - |\n| `codeExecutions.byId` | `public` | (`id`) => [`CodeExecution`](../../code-execution/classes/CodeExecution.md) | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the session was created. | - |\n| <a id=\"property-harness\"></a> `harness` | `readonly` | () => `Promise`\\<`string`\\> | The agent harness implementation serving the session. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-instructions\"></a> `instructions` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Instructions the session's runtime works under, when any were stated at creation. Fixed for the session's life. | - |\n| <a id=\"property-isarchived\"></a> `isArchived` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the session is archived and read-only. | - |\n| <a id=\"property-model\"></a> `model` | `readonly` | () => `Promise`\\<`string`\\> | The model currently configured for the session. | - |\n| <a id=\"property-modifiedat\"></a> `modifiedAt` | `readonly` | () => `Promise`\\<`string`\\> | When the session was last modified. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | The session's user-facing display name. | - |\n| <a id=\"property-repourl\"></a> `repoUrl` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | The repository the agent works with, when one was supplied. | - |\n| <a id=\"property-reviews\"></a> `reviews` | `readonly` | \\{ `byId`: (`id`) => [`SessionReview`](../../review/classes/SessionReview.md); `create`: (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\>; \\} | Persisted reviews scoped to this session, with or without a code execution. | - |\n| `reviews.byId` | `public` | (`id`) => [`SessionReview`](../../review/classes/SessionReview.md) | - | - |\n| `reviews.create` | `public` | (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\> | - | - |\n| <a id=\"property-sandboxsize\"></a> `sandboxSize` | `readonly` | () => `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\> | Compute tier of the managed sandbox. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`SessionStatusDto`](../../../../../generated/agent-harness/types.gen/type-aliases/SessionStatusDto.md)\\> | The session's latest runtime status. | - |\n\n## Methods\n\n### archive()\n\n> **archive**(): `Promise`\\<`void`\\>\n\nArchive this session, making it read-only until unarchived.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### changes()\n\n> **changes**(): `Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\nRead the latest captured GitHub pull request changes and capture status.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\n***\n\n### changesPatch()\n\n> **changesPatch**(): `Promise`\\<`string`\\>\n\nRead the unified diff of the latest captured changeset.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### control()\n\n> **control**(`action`): `Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\nSend a prompt or lifecycle operation to the live agent session.\n\nThe returned `actionId` matches `requestId` on the folded message the\naction derives once it dispatches. A `queued` status means a turn was\nrunning: the action waits in the session's queue ([queue](#queue)) and\ndispatches when that turn ends.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `action` | [`AgentAction`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentAction.md) |\n\n#### Returns\n\n`Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this session and any live resources it owns.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### linkPullRequest()\n\n> **linkPullRequest**(`url`): `Promise`\\<`void`\\>\n\nLink the GitHub pull request at `url` to this session. Linking one that\nis already linked changes nothing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### log()\n\n> **log**(): `Promise`\\<[`AgentSessionLogResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md)\\>\n\nRead the complete raw protocol log for this session.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionLogResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionLogResponse.md)\\>\n\n***\n\n### prompt()\n\n> **prompt**(`text`, `attachments?`): `Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\nSend a prompt to the session — sugar over [control](#control).\n\n`attachments` are files the prompt refers to, each by a URL the agent\ncan fetch (a static file service URL in practice); they reach the agent\nas ACP `resource_link` blocks after the text.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `text` | `string` |\n| `attachments?` | [`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[] |\n\n#### Returns\n\n`Promise`\\<[`ControlResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/ControlResponse.md)\\>\n\n***\n\n### pullRequests()\n\n> **pullRequests**(): `Promise`\\<[`SessionPullRequest`](../type-aliases/SessionPullRequest.md)[]\\>\n\nThe GitHub pull requests linked to this session: the one its agent\nopened and any a person linked, oldest first.\n\n#### Returns\n\n`Promise`\\<[`SessionPullRequest`](../type-aliases/SessionPullRequest.md)[]\\>\n\n***\n\n### queue()\n\n> **queue**(): `Promise`\\<[`QueuedAction`](../../queued-action/classes/QueuedAction.md)[]\\>\n\nThe actions waiting to dispatch in this session, oldest first. Each can\nbe edited or removed until it dispatches.\n\n#### Returns\n\n`Promise`\\<[`QueuedAction`](../../queued-action/classes/QueuedAction.md)[]\\>\n\n***\n\n### refreshChanges()\n\n> **refreshChanges**(): `Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\nRequest a fresh capture and return the current state while it runs.\n\n#### Returns\n\n`Promise`\\<[`AgentSessionChangesResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionChangesResponse.md)\\>\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename this session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setSandboxSize()\n\n> **setSandboxSize**(`size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nResize this session's sandbox and remember the size as the owner's default.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`AgentSessionResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentSessionResponse.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### toolApprovalById()\n\n> **toolApprovalById**(`id`): [`ToolApproval`](../../tool-approval/classes/ToolApproval.md)\n\nConstruct an approval handle scoped to this session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`ToolApproval`](../../tool-approval/classes/ToolApproval.md)\n\n***\n\n### unarchive()\n\n> **unarchive**(): `Promise`\\<`void`\\>\n\nRestore an archived session so it can be edited and prompted again.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### unlinkPullRequest()\n\n> **unlinkPullRequest**(`url`): `Promise`\\<`void`\\>\n\nUnlink a GitHub pull request a person linked to this session. The pull\nrequest the session's agent opened stays linked.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### updateSharePermissions()\n\n> **updateSharePermissions**(`options`): `Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nReplace sharing grants.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SharePermissionOptions`](../../../sharing/permissions/type-aliases/SharePermissionOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/agent-harness/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `AgentSession`\n\nA handle to an agent session by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`AgentSession`\n\n***\n\n### codingPreferences()\n\n> `static` **codingPreferences**(`client`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nWhat the caller's new coding sessions are told to do beyond their assignment.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### createManaged()\n\n> `static` **createManaged**(`client`, `opts?`): `Promise`\\<`AgentSession`\\>\n\nCreate a managed session, optionally delivering its first prompt.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | [`CreateManagedSessionOptions`](../type-aliases/CreateManagedSessionOptions.md) |\n\n#### Returns\n\n`Promise`\\<`AgentSession`\\>\n\n***\n\n### defaultSandboxSize()\n\n> `static` **defaultSandboxSize**(`client`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nThe caller's default sandbox size for new `@coder` sessions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### forPullRequest()\n\n> `static` **forPullRequest**(`client`, `url`): `Promise`\\<`AgentSession`[]\\>\n\nThe sessions linked to the GitHub pull request at `url` that the caller\ncan view, oldest link first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`AgentSession`[]\\>\n\n***\n\n### repositories()\n\n> `static` **repositories**(`client`): `Promise`\\<[`SelectableRepository`](../type-aliases/SelectableRepository.md)[]\\>\n\nThe GitHub repositories the caller can hand a managed session: every\nrepository under an installation of Macro's GitHub App they or their\nteams made, sorted by `owner/name`. Empty when the App is installed\nnowhere they reach.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`SelectableRepository`](../type-aliases/SelectableRepository.md)[]\\>\n\n***\n\n### repositoryBranches()\n\n> `static` **repositoryBranches**(`client`, `repoUrl`): `Promise`\\<`string`[]\\>\n\nBranch names on one repository the caller can start a managed session\nfrom, in the order GitHub listed them. Empty when the repository has\nno commits yet. `repoUrl` is one of the URLs [AgentSession.repositories](#repositories)\nlists.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `repoUrl` | `string` |\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### setCodingPreferences()\n\n> `static` **setCodingPreferences**(`client`, `preferences`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nReplace the caller's coding preferences.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `preferences` | [`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md) |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### setDefaultSandboxSize()\n\n> `static` **setDefaultSandboxSize**(`client`, `size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nSet the caller's default sandbox size for the next `@coder` mention.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/CreateManagedSessionOptions.md -->\n# Type Alias: CreateManagedSessionOptions\n\n> **CreateManagedSessionOptions** = \\{ `instructions?`: `string`; `model?`: `string`; `prompt?`: `string`; `repoBranch?`: `string`; `repoUrl?`: `string`; \\}\n\nWhat a managed session is created with.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-instructions\"></a> `instructions?` | `string` | Instructions the session's runtime works under, fixed for its life. |\n| <a id=\"property-model\"></a> `model?` | `string` | The model the session runs on, instead of its persona's. The session's model from creation, read back as [AgentSession.model](../classes/AgentSession.md#property-model). |\n| <a id=\"property-prompt\"></a> `prompt?` | `string` | First prompt to deliver once the session is running. |\n| <a id=\"property-repobranch\"></a> `repoBranch?` | `string` | The branch the session starts on; needs `repoUrl`. Omitted, the repository's default branch. |\n| <a id=\"property-repourl\"></a> `repoUrl?` | `string` | The repository the session works on, as one of the URLs [AgentSession.repositories](../classes/AgentSession.md#repositories) lists for the caller. Omitted, the runtime chooses from the prompt. Honored for Cursor sessions. |\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/SelectableRepository.md -->\n# Type Alias: SelectableRepository\n\n> **SelectableRepository** = \\{ `defaultBranch?`: `string`; `url`: `string`; \\}\n\nA GitHub repository the caller can point a managed session at.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-defaultbranch\"></a> `defaultBranch?` | `string` | The branch its clones check out, and where a session starts unless `createManaged` names another. Absent for a repository with no commits. |\n| <a id=\"property-url\"></a> `url` | `string` | The canonical `https://github.com/owner/name` URL, as `createManaged` takes it. |\n\n\n<!-- src/entities/agent-sessions/agent-session/type-aliases/SessionPullRequest.md -->\n# Type Alias: SessionPullRequest\n\n> **SessionPullRequest** = \\{ `createdAt`: `string`; `githubKey`: `string`; `linkedBy?`: [`User`](../../../users/user/classes/User.md); `source`: [`PullRequestLinkSource`](../../../../../generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md); `url`: `string`; \\}\n\nA GitHub pull request linked to a session.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When it was linked. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The pull request's `owner/repo/pull/number` key. |\n| <a id=\"property-linkedby\"></a> `linkedBy?` | [`User`](../../../users/user/classes/User.md) | Who linked it, for pull requests a person linked. |\n| <a id=\"property-source\"></a> `source` | [`PullRequestLinkSource`](../../../../../generated/agent-harness/types.gen/type-aliases/PullRequestLinkSource.md) | Whether the session's agent opened it or a person linked it. |\n| <a id=\"property-url\"></a> `url` | `string` | The pull request's GitHub URL. |\n\n\n<!-- src/entities/agent-sessions/code-execution/classes/CodeExecution.md -->\n# Class: CodeExecution\n\nA saved code execution belonging to one agent session.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | () => `Promise`\\<[`RecordedToolCall`](../../../../../generated/agent-harness/types.gen/type-aliases/RecordedToolCall.md)[]\\> | Legacy bridge calls; direct HTTP executions leave this empty. | - |\n| <a id=\"property-error\"></a> `error` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Execution failure text, when present. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-reviews\"></a> `reviews` | `readonly` | \\{ `create`: (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\>; `list`: () => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)[]\\>; \\} | Persistent UI blocks, independent of the execution lifetime. | - |\n| `reviews.create` | `public` | (`input`) => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)\\> | - | - |\n| `reviews.list` | `public` | () => `Promise`\\<[`SessionReview`](../../review/classes/SessionReview.md)[]\\> | - | - |\n| <a id=\"property-source\"></a> `source` | `readonly` | () => `Promise`\\<`string`\\> | The submitted JavaScript module source. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`ExecutionStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionStatus.md)\\> | Saved execution state. Call refresh to observe subsequent changes. | - |\n\n## Methods\n\n### refresh()\n\n> **refresh**(): `Promise`\\<`CodeExecution`\\>\n\nReload the saved state, for example after a running execution completes.\n\n#### Returns\n\n`Promise`\\<`CodeExecution`\\>\n\n***\n\n### result()\n\n> **result**(): `Promise`\\<`unknown`\\>\n\nThe program's returned JSON; preserves an explicit null result.\n\n#### Returns\n\n`Promise`\\<`unknown`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nThe session this execution belongs to.\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ExecutionRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ExecutionRecord.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `CodeExecution`\n\nConstruct a lazy execution handle within its owning session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`CodeExecution`\n\n\n<!-- src/entities/agent-sessions/code-execution/type-aliases/CodeResult.md -->\n# Type Alias: CodeResult\n\n> **CodeResult** = \\{ `data`: [`JsonValue`](JsonValue.md); `reviews`: \\{ `id`: `string`; `kind`: `\"email\"` \\| `\"calendar\"`; \\}[]; \\}\n\nJSON data returned to the model, plus references to independently saved UI.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-data\"></a> `data` | [`JsonValue`](JsonValue.md) |\n| <a id=\"property-reviews\"></a> `reviews` | \\{ `id`: `string`; `kind`: `\"email\"` \\| `\"calendar\"`; \\}[] |\n\n\n<!-- src/entities/agent-sessions/code-execution/type-aliases/JsonValue.md -->\n# Type Alias: JsonValue\n\n> **JsonValue** = `null` \\| `boolean` \\| `number` \\| `string` \\| `JsonValue`[] \\| \\{\\[`key`: `string`\\]: `JsonValue`; \\}\n\n\n<!-- src/entities/agent-sessions/conversation/classes/AgentConversation.md -->\n# Class: AgentConversation\n\nAn agent's conversation in one channel.\n\n## Constructors\n\n### Constructor\n\n> **new AgentConversation**(`client`, `channel`, `record`): `AgentConversation`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `channel` | [`Channel`](../../../channels/channel/classes/Channel.md) | Parent channel. |\n| `record` | [`AgentConversationDto`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentConversationDto.md) | - |\n\n#### Returns\n\n`AgentConversation`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-channel\"></a> `channel` | `readonly` | [`Channel`](../../../channels/channel/classes/Channel.md) | Parent channel. |\n\n## Methods\n\n### agent()\n\n> **agent**(): [`Agent`](../../../agents/agent/classes/Agent.md)\n\nThe agent taking part.\n\n#### Returns\n\n[`Agent`](../../../agents/agent/classes/Agent.md)\n\n***\n\n### sessions()\n\n> **sessions**(): \\{ `createdAt`: `string`; `isCurrent`: `boolean`; `session`: [`AgentSession`](../../agent-session/classes/AgentSession.md); \\}[]\n\nConversation sessions with their current flag.\n\n#### Returns\n\n\\{ `createdAt`: `string`; `isCurrent`: `boolean`; `session`: [`AgentSession`](../../agent-session/classes/AgentSession.md); \\}[]\n\n***\n\n### startFresh()\n\n> **startFresh**(`session`): `Promise`\\<`void`\\>\n\nStart a fresh conversation from one of its sessions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `agentId`: `string`; `channelId`: `string`; \\}\n\nSerialize scoped identity.\n\n#### Returns\n\n\\{ `agentId`: `string`; `channelId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `agentId` | `string` |\n| `channelId` | `string` |\n\n***\n\n### turns()\n\n> **turns**(): [`ConversationTurn`](ConversationTurn.md)[]\n\nRecorded conversation turns.\n\n#### Returns\n\n[`ConversationTurn`](ConversationTurn.md)[]\n\n\n<!-- src/entities/agent-sessions/conversation/classes/ConversationTurn.md -->\n# Class: ConversationTurn\n\nOne agent conversation turn, identified by its source message.\n\n## Constructors\n\n### Constructor\n\n> **new ConversationTurn**(`client`, `conversation`, `record`): `ConversationTurn`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `conversation` | [`AgentConversation`](AgentConversation.md) | Parent conversation. |\n| `record` | [`AgentConversationTurnDto`](../../../../../generated/agent-harness/types.gen/type-aliases/AgentConversationTurnDto.md) | - |\n\n#### Returns\n\n`ConversationTurn`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-conversation\"></a> `conversation` | `readonly` | [`AgentConversation`](AgentConversation.md) | Parent conversation. |\n\n## Methods\n\n### retry()\n\n> **retry**(`actionId`): `Promise`\\<`void`\\>\n\nRetry with a caller persisted action nonce. Never retries automatically.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `actionId` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nSession that handled this turn.\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### source()\n\n> **source**(): [`Message`](../../../channels/message/classes/Message.md)\n\nOriginating message.\n\n#### Returns\n\n[`Message`](../../../channels/message/classes/Message.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `channelId`: `string`; `sourceMessageId`: `string`; \\}\n\nSerialize scoped identity.\n\n#### Returns\n\n\\{ `channelId`: `string`; `sourceMessageId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `channelId` | `string` |\n| `sourceMessageId` | `string` |\n\n\n<!-- src/entities/agent-sessions/namespace/classes/AgentSessionNamespace.md -->\n# Class: AgentSessionNamespace\n\nEntry point for coding-agent sessions.\n\n## Constructors\n\n### Constructor\n\n> **new AgentSessionNamespace**(`client`): `AgentSessionNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`AgentSessionNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\nA handle to an agent session by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### codingPreferences()\n\n> **codingPreferences**(): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nWhat the caller's new coding sessions are told to do beyond their assignment.\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### createManaged()\n\n> **createManaged**(`opts?`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\nCreate a managed agent session.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`CreateManagedSessionOptions`](../../agent-session/type-aliases/CreateManagedSessionOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)\\>\n\n***\n\n### defaultSandboxSize()\n\n> **defaultSandboxSize**(): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nThe caller's default sandbox size for new `@coder` sessions.\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\nThe sessions linked to the GitHub pull request at `url` that the caller\ncan view.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`AgentSession`](../../agent-session/classes/AgentSession.md)[]\\>\n\n***\n\n### repositories()\n\n> **repositories**(): `Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\nThe GitHub repositories the caller can hand a managed session, with the\nbranch each one's sessions start on by default.\n\n#### Returns\n\n`Promise`\\<[`SelectableRepository`](../../agent-session/type-aliases/SelectableRepository.md)[]\\>\n\n***\n\n### repositoryBranches()\n\n> **repositoryBranches**(`repoUrl`): `Promise`\\<`string`[]\\>\n\nBranch names on one repository the caller can start a managed session\nfrom. `repoUrl` is one of the URLs [AgentSessionNamespace.repositories](#repositories)\nlists.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `repoUrl` | `string` |\n\n#### Returns\n\n`Promise`\\<`string`[]\\>\n\n***\n\n### setCodingPreferences()\n\n> **setCodingPreferences**(`preferences`): `Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\nReplace the caller's coding preferences.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `preferences` | [`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md) |\n\n#### Returns\n\n`Promise`\\<[`CodingPreferencesBody`](../../../../../generated/agent-harness/types.gen/type-aliases/CodingPreferencesBody.md)\\>\n\n***\n\n### setDefaultSandboxSize()\n\n> **setDefaultSandboxSize**(`size`): `Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\nSet the caller's default sandbox size for the next `@coder` mention.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `size` | [`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md) |\n\n#### Returns\n\n`Promise`\\<[`SandboxSize`](../../../../../generated/agent-harness/types.gen/type-aliases/SandboxSize.md)\\>\n\n\n<!-- src/entities/agent-sessions/queued-action/classes/QueuedAction.md -->\n# Class: QueuedAction\n\nOne action waiting in an agent session's server-side queue: a prompt or a\ncompact accepted while a turn was running, dispatching when that turn\nends. Until then it can be edited (prompts only), steered, or removed; once\nit has dispatched, these actions answer 404 — there is no un-sending.\n\nList-sourced only - there is no per-action GET, only the queue snapshot -\nso this wraps whatever DTO the caller already has, the same shape\n`CrmComment` wraps a list-sourced record, rather than `MacroEntity`'s\nlazy-fetch-by-id.\n\n## Accessors\n\n### actionId\n\n#### Get Signature\n\n> **get** **actionId**(): `string`\n\nThe id the action was accepted under. Once it dispatches, this equals\n`requestId` on the folded message the action derives.\n\n##### Returns\n\n`string`\n\n***\n\n### actorUserId\n\n#### Get Signature\n\n> **get** **actorUserId**(): `string` \\| `undefined`\n\nThe user who queued it, absent when a bot acted on nobody's behalf.\n\n##### Returns\n\n`string` \\| `undefined`\n\n***\n\n### attachments\n\n#### Get Signature\n\n> **get** **attachments**(): [`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[]\n\nFiles the prompt refers to; empty for a compact. Kept through an edit.\n\n##### Returns\n\n[`PromptAttachment`](../../../../../generated/agent-harness/types.gen/type-aliases/PromptAttachment.md)[]\n\n***\n\n### createdAt\n\n#### Get Signature\n\n> **get** **createdAt**(): `string`\n\nWhen the action was accepted, as an RFC 3339 timestamp.\n\n##### Returns\n\n`string`\n\n***\n\n### kind\n\n#### Get Signature\n\n> **get** **kind**(): `string`\n\n`prompt` or `compact`; only turn-occupying actions are ever queued.\n\n##### Returns\n\n`string`\n\n***\n\n### prompt\n\n#### Get Signature\n\n> **get** **prompt**(): `string` \\| `undefined`\n\nThe prompt's raw text, present for prompts only. What an edit replaces.\n\n##### Returns\n\n`string` \\| `undefined`\n\n## Methods\n\n### edit()\n\n> **edit**(`prompt`): `Promise`\\<`QueuedAction`\\>\n\nReplace this queued prompt's text before it dispatches. Returns this\nhandle for chaining; the edit endpoint answers 204, so `prompt` is\napplied locally rather than reread from a response body.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `prompt` | `string` |\n\n#### Returns\n\n`Promise`\\<`QueuedAction`\\>\n\n***\n\n### remove()\n\n> **remove**(): `Promise`\\<`void`\\>\n\nRemove this action from the queue before it dispatches.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### steer()\n\n> **steer**(): `Promise`\\<`void`\\>\n\nMove this action to the front and interrupt the current turn to run it next.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### from()\n\n> `static` **from**(`client`, `sessionId`, `dto`): `QueuedAction`\n\nWrap a queue entry already in hand (e.g. from `AgentSession.queue()`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `sessionId` | `string` |\n| `dto` | [`QueuedActionDto`](../../../../../generated/agent-harness/types.gen/type-aliases/QueuedActionDto.md) |\n\n#### Returns\n\n`QueuedAction`\n\n\n<!-- src/entities/agent-sessions/review/classes/ReviewItem.md -->\n# Class: ReviewItem\n\nAn item handle scopes edits and decisions to its persisted review.\n\n## Constructors\n\n### Constructor\n\n> **new ReviewItem**(`snapshot`, `actions`): `ReviewItem`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `snapshot` | [`ReviewItem`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItem.md) |\n| `actions` | \\{ `dismiss`: () => `Promise`\\<`void`\\>; `edit`: (`draft`) => `Promise`\\<`void`\\>; `submit`: () => `Promise`\\<`void`\\>; \\} |\n| `actions.dismiss` | () => `Promise`\\<`void`\\> |\n| `actions.edit` | (`draft`) => `Promise`\\<`void`\\> |\n| `actions.submit` | () => `Promise`\\<`void`\\> |\n\n#### Returns\n\n`ReviewItem`\n\n## Accessors\n\n### draft\n\n#### Get Signature\n\n> **get** **draft**(): `unknown`\n\n##### Returns\n\n`unknown`\n\n***\n\n### id\n\n#### Get Signature\n\n> **get** **id**(): `string`\n\n##### Returns\n\n`string`\n\n***\n\n### result\n\n#### Get Signature\n\n> **get** **result**(): `unknown`\n\n##### Returns\n\n`unknown`\n\n***\n\n### status\n\n#### Get Signature\n\n> **get** **status**(): [`ReviewItemStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md)\n\n##### Returns\n\n[`ReviewItemStatus`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewItemStatus.md)\n\n## Methods\n\n### dismiss()\n\n> **dismiss**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### edit()\n\n> **edit**(`draft`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `draft` | `unknown` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### submit()\n\n> **submit**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n\n<!-- src/entities/agent-sessions/review/classes/SessionReview.md -->\n# Class: SessionReview\n\nA persistent review remains actionable after the code execution ends.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Inherited from |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-kind\"></a> `kind` | `readonly` | () => `Promise`\\<[`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md)\\> | - |\n| <a id=\"property-title\"></a> `title` | `readonly` | () => `Promise`\\<`string`\\> | - |\n\n## Methods\n\n### dismissAll()\n\n> **dismissAll**(): `Promise`\\<`void`\\>\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### items()\n\n> **items**(): `Promise`\\<[`ReviewItem`](ReviewItem.md)[]\\>\n\n#### Returns\n\n`Promise`\\<[`ReviewItem`](ReviewItem.md)[]\\>\n\n***\n\n### reference()\n\n> **reference**(): `Promise`\\<\\{ `id`: `string`; `kind`: [`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md); \\}\\>\n\nCompact reference for main()'s returned reviews array.\n\n#### Returns\n\n`Promise`\\<\\{ `id`: `string`; `kind`: [`ReviewKind`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewKind.md); \\}\\>\n\n***\n\n### refresh()\n\n> **refresh**(): `Promise`\\<`SessionReview`\\>\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### session()\n\n> **session**(): [`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n#### Returns\n\n[`AgentSession`](../../agent-session/classes/AgentSession.md)\n\n***\n\n### submitAll()\n\n> **submitAll**(): `Promise`\\<`void`\\>\n\nSubmit the saved pending drafts. Never retries a conflict or ambiguous send.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `SessionReview`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`SessionReview`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `execution`, `input`): `Promise`\\<`SessionReview`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `execution` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n| `input` | [`CreateReviewOptions`](../type-aliases/CreateReviewOptions.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### createForSession()\n\n> `static` **createForSession**(`client`, `session`, `input`, `execution?`): `Promise`\\<`SessionReview`\\>\n\nPresent a review in a session without requiring a code execution.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `input` | [`CreateReviewOptions`](../type-aliases/CreateReviewOptions.md) |\n| `execution?` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`\\>\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `session`, `record`): `SessionReview`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `record` | [`ReviewRecord`](../../../../../generated/agent-harness/types.gen/type-aliases/ReviewRecord.md) |\n\n#### Returns\n\n`SessionReview`\n\n***\n\n### list()\n\n> `static` **list**(`client`, `execution`): `Promise`\\<`SessionReview`[]\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `execution` | [`CodeExecution`](../../code-execution/classes/CodeExecution.md) |\n\n#### Returns\n\n`Promise`\\<`SessionReview`[]\\>\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/CreateReviewOptions.md -->\n# Type Alias: CreateReviewOptions\n\n> **CreateReviewOptions** = \\{ `drafts`: [`ReviewEmailDraft`](ReviewEmailDraft.md)[]; `kind`: `\"email\"`; `title`: `string`; \\} \\| \\{ `drafts`: [`ReviewCalendarDraft`](ReviewCalendarDraft.md)[]; `kind`: `\"calendar\"`; `title`: `string`; \\}\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/ReviewCalendarDraft.md -->\n# Type Alias: ReviewCalendarDraft\n\n> **ReviewCalendarDraft** = \\{ `addGoogleMeet?`: `boolean`; `addMacroCall?`: `boolean`; `attendees?`: \\{ `email`: `string`; `isOptional?`: `boolean`; \\}[]; `calendarId?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: `\"default\"` \\| `\"out_of_office\"`; `location?`: `string` \\| `null`; `outOfOffice?`: \\{ `autoDeclineMode?`: `\"decline_none\"` \\| `\"decline_all\"` \\| `\"decline_new_only\"`; `declineMessage?`: `string` \\| `null`; \\} \\| `null`; `recurrenceLines?`: `string`[]; `reminders?`: \\{ `overrides?`: \\{ `method`: `string`; `minutes`: `number`; \\}[]; `useDefault`: `boolean`; \\} \\| `null`; `time`: [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md); `title`: `string`; \\}\n\nCalendar drafts use the existing calendar composer and creation action.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-addgooglemeet\"></a> `addGoogleMeet?` | `boolean` |\n| <a id=\"property-addmacrocall\"></a> `addMacroCall?` | `boolean` |\n| <a id=\"property-attendees\"></a> `attendees?` | \\{ `email`: `string`; `isOptional?`: `boolean`; \\}[] |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` |\n| <a id=\"property-eventtype\"></a> `eventType?` | `\"default\"` \\| `\"out_of_office\"` |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | \\{ `autoDeclineMode?`: `\"decline_none\"` \\| `\"decline_all\"` \\| `\"decline_new_only\"`; `declineMessage?`: `string` \\| `null`; \\} \\| `null` |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] |\n| <a id=\"property-reminders\"></a> `reminders?` | \\{ `overrides?`: \\{ `method`: `string`; `minutes`: `number`; \\}[]; `useDefault`: `boolean`; \\} \\| `null` |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) |\n| <a id=\"property-title\"></a> `title` | `string` |\n\n\n<!-- src/entities/agent-sessions/review/type-aliases/ReviewEmailDraft.md -->\n# Type Alias: ReviewEmailDraft\n\n> **ReviewEmailDraft** = \\{ `attachments?`: \\{ `documentId`: `string`; \\}[]; `bcc?`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; `body`: `string`; `cc?`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; `includeSignature?`: `boolean` \\| `null`; `replyingToId?`: `string` \\| `null`; `subject`: `string`; `to`: \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[]; \\}\n\nMarkdown is rendered by the ordinary email action; the UI can edit each draft.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments?` | \\{ `documentId`: `string`; \\}[] |\n| <a id=\"property-bcc\"></a> `bcc?` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n| <a id=\"property-body\"></a> `body` | `string` |\n| <a id=\"property-cc\"></a> `cc?` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n| <a id=\"property-includesignature\"></a> `includeSignature?` | `boolean` \\| `null` |\n| <a id=\"property-replyingtoid\"></a> `replyingToId?` | `string` \\| `null` |\n| <a id=\"property-subject\"></a> `subject` | `string` |\n| <a id=\"property-to\"></a> `to` | \\{ `email`: `string`; `name?`: `string` \\| `null`; \\}[] |\n\n\n<!-- src/entities/agent-sessions/tool-approval/classes/ToolApproval.md -->\n# Class: ToolApproval\n\nA permission request scoped to its originating agent session.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | Approval identity. |\n| <a id=\"property-session\"></a> `session` | `readonly` | [`AgentSession`](../../agent-session/classes/AgentSession.md) | Owning session. |\n\n## Methods\n\n### answer()\n\n> **answer**(`answer`): `Promise`\\<[`AnswerToolApprovalResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md)\\>\n\nAnswer the approval using the generated discriminated answer contract.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `answer` | [`ToolApprovalAnswerDto`](../../../../../generated/agent-harness/types.gen/type-aliases/ToolApprovalAnswerDto.md) |\n\n#### Returns\n\n`Promise`\\<[`AnswerToolApprovalResponse`](../../../../../generated/agent-harness/types.gen/type-aliases/AnswerToolApprovalResponse.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `id`: `string`; `sessionId`: `string`; \\}\n\nSerialize scoped identity only.\n\n#### Returns\n\n\\{ `id`: `string`; `sessionId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `id` | `string` |\n| `sessionId` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `session`, `id`): `ToolApproval`\n\nConstruct a scoped approval handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `session` | [`AgentSession`](../../agent-session/classes/AgentSession.md) |\n| `id` | `string` |\n\n#### Returns\n\n`ToolApproval`\n"
},
{
"name": "agents",
@@ -83,12 +83,6 @@
"overview": "<!-- src/entities/channels/namespace/classes/ChannelNamespace.md -->\n# Class: ChannelNamespace\n\n## Constructors\n\n### Constructor\n\n> **new ChannelNamespace**(`client`): `ChannelNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`ChannelNamespace`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | [`ChannelLabelsNamespace`](../../labels/classes/ChannelLabelsNamespace.md) | Team-shared labels that group channels in the Chat sidebar. |\n\n## Methods\n\n### activity()\n\n> **activity**(): `Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)[]\\>\n\nRecent channel activity, with channel and user handles.\n\n#### Returns\n\n`Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)[]\\>\n\n***\n\n### byId()\n\n> **byId**(`id`): [`Channel`](../../channel/classes/Channel.md)\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Channel`](../../channel/classes/Channel.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nCreate a channel. The caller becomes the owner.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `opts` | \\{ `name?`: `string`; `participants?`: [`User`](../../../users/user/classes/User.md)[]; `team?`: [`Team`](../../../teams/team/classes/Team.md); `type`: [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md); \\} | - |\n| `opts.name?` | `string` | - |\n| `opts.participants?` | [`User`](../../../users/user/classes/User.md)[] | Participants to add, excluding the owner. |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) | Team, for team channels. |\n| `opts.type` | [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md) | - |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### dm()\n\n> **dm**(`recipient`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `recipient` | [`User`](../../../users/user/classes/User.md) |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### list()\n\n> **list**(): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)[]\\>\n\nAll channels the authenticated user is a member of.\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)[]\\>\n\n***\n\n### private()\n\n> **private**(`recipients`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nOpen (creating if needed) the private group channel with a set of users.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `recipients` | [`User`](../../../users/user/classes/User.md)[] |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nSearch channels by name (client-side fuzzy filter on the full channel list)\nor by content (server-side unified search).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n",
"documentation": "# Macro SDK: channels\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/ActivityType.md -->\n# Type Alias: ActivityType\n\n> **ActivityType** = `\"view\"` \\| `\"interact\"`\n\nThe kind of activity a user performs in a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiActivity.md -->\n# Type Alias: ApiActivity\n\n> **ApiActivity** = \\{ `channel_id`: `string`; `created_at`: `string`; `id`: `string`; `interacted_at?`: `string` \\| `null`; `updated_at`: `string`; `user_id`: `string`; `viewed_at?`: `string` \\| `null`; \\}\n\nA user's activity (view/interaction) within a channel.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | When the activity row was created. |\n| <a id=\"property-id\"></a> `id` | `string` | Activity id. |\n| <a id=\"property-interacted_at\"></a> `interacted_at?` | `string` \\| `null` | The last time the user interacted with the channel. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | When the activity row was last updated. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User id. |\n| <a id=\"property-viewed_at\"></a> `viewed_at?` | `string` \\| `null` | The last time the user viewed the channel. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiChannelAttachment.md -->\n# Type Alias: ApiChannelAttachment\n\n> **ApiChannelAttachment** = \\{ `channel_id`: `string`; `created_at`: `string`; `entity_id`: `string`; `entity_type`: `string`; `height?`: `number` \\| `null`; `id`: `string`; `message_id`: `string`; `sender_id`: `string`; `width?`: `number` \\| `null`; \\}\n\nA channel-level attachment.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | When the attachment was created. |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity id. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Type of entity. |\n| <a id=\"property-height\"></a> `height?` | `number` \\| `null` | Height (for images). |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment id. |\n| <a id=\"property-message_id\"></a> `message_id` | `string` | Message id this attachment belongs to. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | The user who sent the message containing this attachment. |\n| <a id=\"property-width\"></a> `width?` | `number` \\| `null` | Width (for images). |\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiChannelAttachmentsPage.md -->\n# Type Alias: ApiChannelAttachmentsPage\n\n> **ApiChannelAttachmentsPage** = \\{ `items`: [`ApiChannelAttachment`](ApiChannelAttachment.md)[]; `next_cursor?`: `string` \\| `null`; \\}\n\nPaginated response of channel attachments.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-items\"></a> `items` | [`ApiChannelAttachment`](ApiChannelAttachment.md)[] | Attachments on this page. |\n| <a id=\"property-next_cursor\"></a> `next_cursor?` | `string` \\| `null` | Cursor for the next page, null if no more pages. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiChannelDetail.md -->\n# Type Alias: ApiChannelDetail\n\n> **ApiChannelDetail** = \\{ `channel_id`: `string`; `channel_name`: `string`; `channel_type`: [`ChannelType`](ChannelType.md); `participants`: [`ApiChannelParticipant`](ApiChannelParticipant.md)[]; \\}\n\nChannel detail: metadata and active participants.\n\nMessages are read through `/messages/channel/{channel_id}`.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id. |\n| <a id=\"property-channel_name\"></a> `channel_name` | `string` | Resolved display name from the viewer's perspective. |\n| <a id=\"property-channel_type\"></a> `channel_type` | [`ChannelType`](ChannelType.md) | Channel type. |\n| <a id=\"property-participants\"></a> `participants` | [`ApiChannelParticipant`](ApiChannelParticipant.md)[] | Active participants. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiChannelParticipant.md -->\n# Type Alias: ApiChannelParticipant\n\n> **ApiChannelParticipant** = \\{ `channel_id`: `string`; `joined_at`: `string`; `role`: [`ApiParticipantRole`](ApiParticipantRole.md); `user_id`: `string`; \\}\n\nA channel participant.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id. |\n| <a id=\"property-joined_at\"></a> `joined_at` | `string` | When the user joined. |\n| <a id=\"property-role\"></a> `role` | [`ApiParticipantRole`](ApiParticipantRole.md) | Role in the channel. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User id. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiParticipantRole.md -->\n# Type Alias: ApiParticipantRole\n\n> **ApiParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nParticipant role in a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/BotSenderProfile.md -->\n# Type Alias: BotSenderProfile\n\n> **BotSenderProfile** = \\{ `avatar_url?`: `string` \\| `null`; `name`: `string`; \\}\n\nPublic bot profile attached to bot-authored messages.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatar_url\"></a> `avatar_url?` | `string` \\| `null` | Bot avatar URL. |\n| <a id=\"property-name\"></a> `name` | `string` | Bot display name. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelLabel.md -->\n# Type Alias: ChannelLabel\n\n> **ChannelLabel** = \\{ `channelCount`: `number`; `channelIds`: `string`[]; `createdAt`: `string`; `id`: `string`; `name`: `string`; `rule?`: `null` \\| [`ChannelLabelRule`](ChannelLabelRule.md); `sortOrder`: `number`; `teamId?`: `string` \\| `null`; `updatedAt`: `string`; \\}\n\nA shared or account-private label grouping chat channels in the sidebar.\n\n`channel_ids` is viewer-relative: it lists only the labelled channels the\nrequesting user participates in. `channel_count` counts every channel in\nthe label so clients can warn accurately before a delete.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelcount\"></a> `channelCount` | `number` | All assignments for a manual label; visible matches for a smart tag. |\n| <a id=\"property-channelids\"></a> `channelIds` | `string`[] | Channels in this label that the requesting user participates in. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the label was created. |\n| <a id=\"property-id\"></a> `id` | `string` | Stable label id. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name, unique within the scope (case-insensitive). |\n| <a id=\"property-rule\"></a> `rule?` | `null` \\| [`ChannelLabelRule`](ChannelLabelRule.md) | - |\n| <a id=\"property-sortorder\"></a> `sortOrder` | `number` | Manual ordering value within the scope; lower sorts first. |\n| <a id=\"property-teamid\"></a> `teamId?` | `string` \\| `null` | Owning team, or `None` for account-private labels. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | When the label was last renamed or reordered. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelLabelRule.md -->\n# Type Alias: ChannelLabelRule\n\n> **ChannelLabelRule** = \\{ `attribute`: `\"name\"`; `contains`: `string`; \\}\n\nCase-insensitive, literal substring matching on the channel name.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attribute\"></a> `attribute` | `\"name\"` | - |\n| <a id=\"property-contains\"></a> `contains` | `string` | The substring to find anywhere in the name. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelType.md -->\n# Type Alias: ChannelType\n\n> **ChannelType** = `\"public\"` \\| `\"private\"` \\| `\"direct_message\"` \\| `\"team\"`\n\nType of channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/CountedReaction.md -->\n# Type Alias: CountedReaction\n\n> **CountedReaction** = \\{ `emoji`: `string`; `users`: `string`[]; \\}\n\nReaction emoji and the users who added it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emoji\"></a> `emoji` | `string` | Emoji being reacted with. |\n| <a id=\"property-users\"></a> `users` | `string`[] | User identifiers. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentId.md -->\n# Type Alias: DocumentId\n\n> **DocumentId** = `string`\n\nA validated document identifier. Historical document ids need not be UUIDs.\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/GetChannelAttachmentsResponses.md -->\n# Type Alias: GetChannelAttachmentsResponses\n\n> **GetChannelAttachmentsResponses** = \\{ `200`: [`ApiChannelAttachmentsPage`](ApiChannelAttachmentsPage.md); \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`ApiChannelAttachmentsPage`](ApiChannelAttachmentsPage.md) |\n\n\n<!-- generated/storage/types.gen/type-aliases/GetChannelParticipantsResponses.md -->\n# Type Alias: GetChannelParticipantsResponses\n\n> **GetChannelParticipantsResponses** = \\{ `200`: [`ApiChannelParticipant`](ApiChannelParticipant.md)[]; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-200\"></a> `200` | [`ApiChannelParticipant`](ApiChannelParticipant.md)[] |\n\n\n<!-- generated/storage/types.gen/type-aliases/ImportedAuthor.md -->\n# Type Alias: ImportedAuthor\n\n> **ImportedAuthor** = \\{ `name`: `string`; \\}\n\nDisplay attribution for a comment imported from an external document.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name` | `string` | Original author text; never interpreted as an authenticated principal. |\n\n\n<!-- generated/storage/types.gen/type-aliases/Message.md -->\n# Type Alias: Message\n\n> **Message** = \\{ `attachments`: [`MessageAttachment`](MessageAttachment.md)[]; `bot_profile?`: `null` \\| [`BotSenderProfile`](BotSenderProfile.md); `content`: `string`; `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `edited_at?`: `string` \\| `null`; `guest_name?`: `string` \\| `null`; `id`: `string`; `imported_author?`: `null` \\| [`ImportedAuthor`](ImportedAuthor.md); `mentions`: [`SimpleMention`](SimpleMention.md)[]; `parent`: [`MessageParent`](MessageParent.md); `reactions`: [`CountedReaction`](CountedReaction.md)[]; `sender_id`: `string`; `thread_id?`: `string` \\| `null`; `triggered_by?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nShared message representation for channel timelines and entity discussions.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`MessageAttachment`](MessageAttachment.md)[] | Attached entities. |\n| <a id=\"property-bot_profile\"></a> `bot_profile?` | `null` \\| [`BotSenderProfile`](BotSenderProfile.md) | - |\n| <a id=\"property-content\"></a> `content` | `string` | Macro Markdown body. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Message tombstone, independent of thread deletion. |\n| <a id=\"property-edited_at\"></a> `edited_at?` | `string` \\| `null` | Last content edit, if any. |\n| <a id=\"property-guest_name\"></a> `guest_name?` | `string` \\| `null` | Display name of a verified call guest, retained after the call ends. |\n| <a id=\"property-id\"></a> `id` | `string` | Message UUID. |\n| <a id=\"property-imported_author\"></a> `imported_author?` | `null` \\| [`ImportedAuthor`](ImportedAuthor.md) | - |\n| <a id=\"property-mentions\"></a> `mentions` | [`SimpleMention`](SimpleMention.md)[] | Tracked mentions, retained when a caller changes attachments only. |\n| <a id=\"property-parent\"></a> `parent` | [`MessageParent`](MessageParent.md) | Entity that owns this conversation. |\n| <a id=\"property-reactions\"></a> `reactions` | [`CountedReaction`](CountedReaction.md)[] | Aggregated reactions. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Authenticated actor or owner of imported content. |\n| <a id=\"property-thread_id\"></a> `thread_id?` | `string` \\| `null` | Root message UUID for replies; absent on roots. |\n| <a id=\"property-triggered_by\"></a> `triggered_by?` | `string` \\| `null` | User who triggered a bot-authored message. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last persisted update. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageAttachment.md -->\n# Type Alias: MessageAttachment\n\n> **MessageAttachment** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: `string`; `height?`: `number` \\| `null`; `id`: `string`; `width?`: `number` \\| `null`; \\}\n\nAn entity attached to a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | When the attachment was added. |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Attached entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Attached entity type. |\n| <a id=\"property-height\"></a> `height?` | `number` \\| `null` | Optional media height. |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment UUID. |\n| <a id=\"property-width\"></a> `width?` | `number` \\| `null` | Optional media width. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `id`: `string`; `type`: `\"channel\"`; \\} \\| \\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\} \\| \\{ `id`: `string`; `type`: `\"initiative\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_company\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_contact\"`; \\} \\| \\{ `id`: `string`; `type`: `\"call\"`; \\}\n\nThe entity whose permissions and lifecycle govern a message.\n\n## Union Members\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A channel, including direct messages. |\n| `type` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | [`DocumentId`](DocumentId.md) | A document, including tasks and PDFs. |\n| `type` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | An initiative, presented as a project in the application. |\n| `type` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_company\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM company. |\n| `type` | `\"crm_company\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_contact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM contact. |\n| `type` | `\"crm_contact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A video call and its persistent chat thread. |\n| `type` | `\"call\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/SimpleMention.md -->\n# Type Alias: SimpleMention\n\n> **SimpleMention** = \\{ `entity_id`: `string`; `entity_type`: `string`; \\}\n\nA mention tracked in a message body.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Mentioned entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Mentioned entity type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SmartTagChannelMatch.md -->\n# Type Alias: SmartTagChannelMatch\n\n> **SmartTagChannelMatch** = \\{ `id`: `string`; `name`: `string`; \\}\n\nA channel visible to the caller that matches a smart tag rule.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | Channel id. |\n| <a id=\"property-name\"></a> `name` | `string` | Channel display name. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SmartTagPreview.md -->\n# Type Alias: SmartTagPreview\n\n> **SmartTagPreview** = \\{ `channels`: [`SmartTagChannelMatch`](SmartTagChannelMatch.md)[]; `totalCount`: `number`; \\}\n\nA bounded preview and the total number of visible channels matching a rule.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channels\"></a> `channels` | [`SmartTagChannelMatch`](SmartTagChannelMatch.md)[] | First matches, in alphabetical order. |\n| <a id=\"property-totalcount\"></a> `totalCount` | `number` | Number of matching channels the caller participates in, including overflow. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/channels/activity/classes/ChannelActivity.md -->\n# Class: ChannelActivity\n\nA user's channel activity marker.\n\n## Constructors\n\n### Constructor\n\n> **new ChannelActivity**(`client`, `channel`, `record`): `ChannelActivity`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `channel` | [`Channel`](../../channel/classes/Channel.md) | Related channel. |\n| `record` | [`ApiActivity`](../../../../../generated/storage/types.gen/type-aliases/ApiActivity.md) | - |\n\n#### Returns\n\n`ChannelActivity`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-channel\"></a> `channel` | `readonly` | [`Channel`](../../channel/classes/Channel.md) | Related channel. |\n\n## Accessors\n\n### id\n\n#### Get Signature\n\n> **get** **id**(): `string`\n\nActivity identity.\n\n##### Returns\n\n`string`\n\n## Methods\n\n### createdAt()\n\n> **createdAt**(): `string`\n\nCreation time.\n\n#### Returns\n\n`string`\n\n***\n\n### recordInteraction()\n\n> **recordInteraction**(`type`): `Promise`\\<`ChannelActivity`\\>\n\nRecord a view or interaction in this channel.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `type` | [`ActivityType`](../../../../../generated/storage/types.gen/type-aliases/ActivityType.md) |\n\n#### Returns\n\n`Promise`\\<`ChannelActivity`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): [`ApiActivity`](../../../../../generated/storage/types.gen/type-aliases/ApiActivity.md)\n\nSerialize activity without credentials.\n\n#### Returns\n\n[`ApiActivity`](../../../../../generated/storage/types.gen/type-aliases/ApiActivity.md)\n\n***\n\n### user()\n\n> **user**(): [`User`](../../../users/user/classes/User.md)\n\nUser who interacted.\n\n#### Returns\n\n[`User`](../../../users/user/classes/User.md)\n\n\n<!-- src/entities/channels/channel/classes/Channel.md -->\n# Class: Channel\n\nA channel.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`ChannelDetail`\\>\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"channel\"` | `'channel'` | Favorites identify channels as `channel`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The channel's display name, resolved from the viewer's perspective. | - | - |\n| <a id=\"property-type\"></a> `type` | `readonly` | () => `Promise`\\<[`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md)\\> | `...` | The channel's type (e.g. `public`, `dm`, `private`). | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Channel`\\> | `...` | Search channels by content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### addParticipants()\n\n> **addParticipants**(`users`): `Promise`\\<`void`\\>\n\nAdd users to the channel.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `users` | [`User`](../../../users/user/classes/User.md)[] |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### agentConversations()\n\n> **agentConversations**(): `Promise`\\<[`AgentConversation`](../../../agent-sessions/conversation/classes/AgentConversation.md)[]\\>\n\nConversations maintained by agents in this channel.\n\n#### Returns\n\n`Promise`\\<[`AgentConversation`](../../../agent-sessions/conversation/classes/AgentConversation.md)[]\\>\n\n***\n\n### attachments()\n\n> **attachments**(`opts?`): `AsyncGenerator`\\<[`ApiChannelAttachment`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelAttachment.md)\\>\n\nThe attachments posted in this channel, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `opts?` | \\{ `pageSize?`: `number`; `type?`: `string`; \\} | - |\n| `opts.pageSize?` | `number` | - |\n| `opts.type?` | `string` | Filter by type: `static` for images/videos, `dss` for documents. |\n\n#### Returns\n\n`AsyncGenerator`\\<[`ApiChannelAttachment`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelAttachment.md)\\>\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete the channel. This is not reversible.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Channel`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Channel`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### join()\n\n> **join**(): `Promise`\\<`void`\\>\n\nJoin the channel as the current user.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### joinCode()\n\n> **joinCode**(): `Promise`\\<`string`\\>\n\nA reusable code that lets a user join this channel.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### leave()\n\n> **leave**(): `Promise`\\<`void`\\>\n\nLeave the channel as the current user.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### message()\n\n> **message**(`id`): [`Message`](../../message/classes/Message.md)\n\nA handle to a message in this channel by id.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Message`](../../message/classes/Message.md)\n\n***\n\n### messages()\n\n> **messages**(`opts?`): `AsyncGenerator`\\<[`Message`](../../message/classes/Message.md)\\>\n\nRoot messages in this channel, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `pageSize?`: `number`; \\} |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Message`](../../message/classes/Message.md)\\>\n\n***\n\n### messagesAfter()\n\n> **messagesAfter**(`after`, `opts?`): `AsyncGenerator`\\<[`Message`](../../message/classes/Message.md)\\>\n\nRoot messages created or replied to at or after `after`, most recent\nfirst, auto-paginated. Use it to catch up after a disconnect.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `after` | `string` \\| `Date` |\n| `opts?` | \\{ `pageSize?`: `number`; \\} |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Message`](../../message/classes/Message.md)\\>\n\n***\n\n### messageThreadById()\n\n> **messageThreadById**(`id`): [`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\nA shared message thread scoped to this resource.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\n***\n\n### participants()\n\n> **participants**(): `Promise`\\<[`ApiChannelParticipant`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelParticipant.md)[]\\>\n\nThe channel's members, with their roles and join times.\n\n#### Returns\n\n`Promise`\\<[`ApiChannelParticipant`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelParticipant.md)[]\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### recordActivity()\n\n> **recordActivity**(`type`): `Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)\\>\n\nRecord a view or interaction in this channel.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `type` | [`ActivityType`](../../../../../generated/storage/types.gen/type-aliases/ActivityType.md) |\n\n#### Returns\n\n`Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)\\>\n\n***\n\n### removeParticipants()\n\n> **removeParticipants**(`users`): `Promise`\\<`void`\\>\n\nRemove users from the channel.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `users` | [`User`](../../../users/user/classes/User.md)[] |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the channel.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### send()\n\n> **send**(`body`, `opts?`): `Promise`\\<[`Message`](../../message/classes/Message.md)\\>\n\nPost a message. Plain text, or a rich body composed with `msg`.\n\nWorks with a channel webhook token as well as a normal one — see\n[postToChannel](../../post/functions/postToChannel.md) for which endpoint that picks and what it costs.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) |\n| `opts?` | \\{ `thread?`: [`Thread`](../../thread/classes/Thread.md); \\} |\n| `opts.thread?` | [`Thread`](../../thread/classes/Thread.md) |\n\n#### Returns\n\n`Promise`\\<[`Message`](../../message/classes/Message.md)\\>\n\n***\n\n### setPicture()\n\n> **setPicture**(`picture?`): `Promise`\\<`void`\\>\n\nSet an uploaded profile picture, or clear it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `picture?` | [`ChannelPicture`](../../picture/classes/ChannelPicture.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### timelinePage()\n\n> **timelinePage**(`selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Message`](../../message/classes/Message.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA mixed message and activity timeline page.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `selection?` | [`TimelineOptions`](../../../messages/thread/interfaces/TimelineOptions.md)\\<[`Message`](../../message/classes/Message.md)\\> |\n\n#### Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Message`](../../message/classes/Message.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ApiChannelDetail`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelDetail.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ApiChannelDetail`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelDetail.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ApiChannelDetail`](../../../../../generated/storage/types.gen/type-aliases/ApiChannelDetail.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### typing()\n\n> **typing**(`action`, `opts?`): `Promise`\\<`void`\\>\n\nBroadcast a typing indicator, optionally scoped to a thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `action` | `\"stop\"` \\| `\"start\"` |\n| `opts?` | \\{ `thread?`: [`Thread`](../../thread/classes/Thread.md); \\} |\n| `opts.thread?` | [`Thread`](../../thread/classes/Thread.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Channel`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Channel`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe channel's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Channel`\n\nA handle to a channel by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Channel`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Channel`\\>\n\nCreate a channel. The caller becomes the owner.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `opts` | \\{ `name?`: `string`; `participants?`: [`User`](../../../users/user/classes/User.md)[]; `team?`: [`Team`](../../../teams/team/classes/Team.md); `type`: [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md); \\} | - |\n| `opts.name?` | `string` | - |\n| `opts.participants?` | [`User`](../../../users/user/classes/User.md)[] | Participants to add, excluding the owner. |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) | Team, for team channels. |\n| `opts.type` | [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md) | - |\n\n#### Returns\n\n`Promise`\\<`Channel`\\>\n\n***\n\n### dm()\n\n> `static` **dm**(`client`, `recipient`): `Promise`\\<`Channel`\\>\n\nOpen (creating if needed) the DM channel with a user.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `recipient` | [`User`](../../../users/user/classes/User.md) |\n\n#### Returns\n\n`Promise`\\<`Channel`\\>\n\n***\n\n### private()\n\n> `static` **private**(`client`, `recipients`): `Promise`\\<`Channel`\\>\n\nOpen (creating if needed) the private group channel with a set of users.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `recipients` | [`User`](../../../users/user/classes/User.md)[] |\n\n#### Returns\n\n`Promise`\\<`Channel`\\>\n\n\n<!-- src/entities/channels/channel/type-aliases/ChannelAttachment.md -->\n# Type Alias: ChannelAttachment\n\n> **ChannelAttachment** = [`GetChannelAttachmentsResponses`](../../../../../generated/storage/types.gen/type-aliases/GetChannelAttachmentsResponses.md)\\[`200`\\]\\[`\"items\"`\\]\\[`number`\\]\n\nA file or entity attached to a message in a channel.\n\n\n<!-- src/entities/channels/channel/type-aliases/ChannelParticipant.md -->\n# Type Alias: ChannelParticipant\n\n> **ChannelParticipant** = [`GetChannelParticipantsResponses`](../../../../../generated/storage/types.gen/type-aliases/GetChannelParticipantsResponses.md)\\[`200`\\]\\[`number`\\]\n\nA member of a channel, with their role and join time.\n\n\n<!-- src/entities/channels/labels/classes/ChannelLabelsNamespace.md -->\n# Class: ChannelLabelsNamespace\n\nShared or private channel labels: named groups of channels shown in the Chat\nsidebar. Every member of the team sees the same labels in the same order,\nand any member may create, rename, delete, or move channels between them;\neach change applies to the whole team. Users without a team have private\nlabels belonging to their account.\n\nA label's `channelIds` lists only the channels the authenticated user is a\nmember of. Manual labels count all assignments; smart tags count visible\nmatches. A channel can be in one manual label and any number of matching\nsmart tags per team or account. Direct messages cannot be grouped.\n\n## Constructors\n\n### Constructor\n\n> **new ChannelLabelsNamespace**(`client`): `ChannelLabelsNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`ChannelLabelsNamespace`\n\n## Methods\n\n### create()\n\n> **create**(`name`, `channels?`): `Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\nCreate a label and atomically move `channels` into it. Names are unique\nwithin the team or account, case-insensitively.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `name` | `string` | `undefined` |\n| `channels?` | [`Channel`](../../channel/classes/Channel.md)[] | `[]` |\n\n#### Returns\n\n`Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\n***\n\n### createSmartTag()\n\n> **createSmartTag**(`name`, `rule`): `Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\nCreate a smart tag whose membership follows an attribute rule automatically.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n| `rule` | [`ChannelLabelRule`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabelRule.md) |\n\n#### Returns\n\n`Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\n***\n\n### delete()\n\n> **delete**(`label`): `Promise`\\<`void`\\>\n\nDelete a label for the whole team; its channels return to the plain list.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### list()\n\n> **list**(): `Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)[]\\>\n\nEvery label in the authenticated user's shared or private scope.\n\n#### Returns\n\n`Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)[]\\>\n\n***\n\n### previewSmartTag()\n\n> **previewSmartTag**(`rule`): `Promise`\\<[`SmartTagPreview`](../../../../../generated/storage/types.gen/type-aliases/SmartTagPreview.md)\\>\n\nPreview the first matches and total visible count without creating a tag.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `rule` | [`ChannelLabelRule`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabelRule.md) |\n\n#### Returns\n\n`Promise`\\<[`SmartTagPreview`](../../../../../generated/storage/types.gen/type-aliases/SmartTagPreview.md)\\>\n\n***\n\n### rename()\n\n> **rename**(`label`, `name`): `Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\nRename a label for the whole team.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md) |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\n***\n\n### setLabel()\n\n> **setLabel**(`channel`, `label`): `Promise`\\<`void`\\>\n\nMove a channel into `label`, or out of any label when `label` is `undefined`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `channel` | [`Channel`](../../channel/classes/Channel.md) |\n| `label` | [`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md) \\| `undefined` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### updateSmartTag()\n\n> **updateSmartTag**(`label`, `name`, `rule`): `Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\nUpdate the name and matching rule of an existing smart tag.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `label` | [`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md) |\n| `name` | `string` |\n| `rule` | [`ChannelLabelRule`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabelRule.md) |\n\n#### Returns\n\n`Promise`\\<[`ChannelLabel`](../../../../../generated/storage/types.gen/type-aliases/ChannelLabel.md)\\>\n\n\n<!-- src/entities/channels/message/classes/Message.md -->\n# Class: Message\n\nA message in a channel. A thin handle: `id` and `channelId` are known up\nfront, and record-backed fields (`content`, `author`) load lazily on first\naccess and cache. Actions carry the ids for you.\n\n## Extends\n\n- [`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md)\\<[`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-channelid\"></a> `channelId` | `readonly` | `string` | `undefined` | - | - | - |\n| <a id=\"property-content\"></a> `content` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The message body. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the message was created. | - | - |\n| <a id=\"property-editedat\"></a> `editedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the message was last edited, if it has been. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"channel_message\"` | `'channel_message'` | Favorites identify channel messages as `channel_message`. | [`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`entityType`](../../../entity/classes/FavoritableEntity.md#property-entitytype) | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`id`](../../../entity/classes/FavoritableEntity.md#property-id) |\n| <a id=\"property-mentions\"></a> `mentions` | `readonly` | [`SimpleMention`](../../../../../generated/storage/types.gen/type-aliases/SimpleMention.md)[] | `[]` | Entities mentioned in this message, when a list, thread, or event supplied them. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string`\\> | `...` | When the message was last updated. | - | - |\n\n## Methods\n\n### author()\n\n> **author**(): `Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\nThe user who sent this message.\n\n#### Returns\n\n`Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\n***\n\n### channel()\n\n> **channel**(): [`Channel`](../../channel/classes/Channel.md)\n\nThe channel this message is in.\n\n#### Returns\n\n[`Channel`](../../channel/classes/Channel.md)\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this message.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### edit()\n\n> **edit**(`body`): `Promise`\\<`Message`\\>\n\nReplace this message's body.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Message`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n#### Inherited from\n\n[`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`favorite`](../../../entity/classes/FavoritableEntity.md#favorite)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`permission`](../../../entity/classes/FavoritableEntity.md#permission)\n\n***\n\n### react()\n\n> **react**(`emoji`): `Promise`\\<`Message`\\>\n\nAdd an emoji reaction to this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `emoji` | `string` |\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n***\n\n### reply()\n\n> **reply**(`body`): `Promise`\\<`Message`\\>\n\nPost a reply in this message's thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) |\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n***\n\n### thread()\n\n> **thread**(): [`Thread`](../../thread/classes/Thread.md)\n\nThe thread rooted at this message.\n\n#### Returns\n\n[`Thread`](../../thread/classes/Thread.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`toJSON`](../../../entity/classes/FavoritableEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Message`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n#### Inherited from\n\n[`FavoritableEntity`](../../../entity/classes/FavoritableEntity.md).[`unfavorite`](../../../entity/classes/FavoritableEntity.md#unfavorite)\n\n***\n\n### unreact()\n\n> **unreact**(`emoji`): `Promise`\\<`Message`\\>\n\nRemove one of your emoji reactions from this message.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `emoji` | `string` |\n\n#### Returns\n\n`Promise`\\<`Message`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `channelId`, `id`, `mentions?`): `Message`\n\nA handle to a message by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | `undefined` |\n| `channelId` | `string` | `undefined` |\n| `id` | `string` | `undefined` |\n| `mentions?` | [`SimpleMention`](../../../../../generated/storage/types.gen/type-aliases/SimpleMention.md)[] | `[]` |\n\n#### Returns\n\n`Message`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `channelId`, `data`): `Message`\n\nBuild a root or reply from a message record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `channelId` | `string` |\n| `data` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md) |\n\n#### Returns\n\n`Message`\n\n\n<!-- src/entities/channels/message/type-aliases/MessageData.md -->\n# Type Alias: MessageData\n\n> **MessageData** = [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md)\n\nThe API's representation of a message; the same record the document comment API returns.\n\n\n<!-- src/entities/channels/namespace/classes/ChannelNamespace.md -->\n# Class: ChannelNamespace\n\n## Constructors\n\n### Constructor\n\n> **new ChannelNamespace**(`client`): `ChannelNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`ChannelNamespace`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-labels\"></a> `labels` | `readonly` | [`ChannelLabelsNamespace`](../../labels/classes/ChannelLabelsNamespace.md) | Team-shared labels that group channels in the Chat sidebar. |\n\n## Methods\n\n### activity()\n\n> **activity**(): `Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)[]\\>\n\nRecent channel activity, with channel and user handles.\n\n#### Returns\n\n`Promise`\\<[`ChannelActivity`](../../activity/classes/ChannelActivity.md)[]\\>\n\n***\n\n### byId()\n\n> **byId**(`id`): [`Channel`](../../channel/classes/Channel.md)\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Channel`](../../channel/classes/Channel.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nCreate a channel. The caller becomes the owner.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `opts` | \\{ `name?`: `string`; `participants?`: [`User`](../../../users/user/classes/User.md)[]; `team?`: [`Team`](../../../teams/team/classes/Team.md); `type`: [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md); \\} | - |\n| `opts.name?` | `string` | - |\n| `opts.participants?` | [`User`](../../../users/user/classes/User.md)[] | Participants to add, excluding the owner. |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) | Team, for team channels. |\n| `opts.type` | [`ChannelType`](../../../../../generated/storage/types.gen/type-aliases/ChannelType.md) | - |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### dm()\n\n> **dm**(`recipient`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `recipient` | [`User`](../../../users/user/classes/User.md) |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### list()\n\n> **list**(): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)[]\\>\n\nAll channels the authenticated user is a member of.\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)[]\\>\n\n***\n\n### private()\n\n> **private**(`recipients`): `Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nOpen (creating if needed) the private group channel with a set of users.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `recipients` | [`User`](../../../users/user/classes/User.md)[] |\n\n#### Returns\n\n`Promise`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\nSearch channels by name (client-side fuzzy filter on the full channel list)\nor by content (server-side unified search).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Channel`](../../channel/classes/Channel.md)\\>\n\n\n<!-- src/entities/channels/picture/classes/ChannelPicture.md -->\n# Class: ChannelPicture\n\nAn uploaded channel profile picture in static file storage.\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` |\n\n## Methods\n\n### toJSON()\n\n> **toJSON**(): \\{ `id`: `string`; \\}\n\nSerialize the uploaded picture reference.\n\n#### Returns\n\n\\{ `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`id`): `ChannelPicture`\n\nConstruct a reference from the upload receipt.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n`ChannelPicture`\n\n\n<!-- src/entities/channels/post/functions/postToChannel.md -->\n# Function: postToChannel()\n\n> **postToChannel**(`client`, `target`, `body`): `Promise`\\<`string`\\>\n\nPost a message using the endpoint supported by the caller's credentials.\n\nMost credentials use `POST /messages/channel/{id}`. User-owned bots without\nan acting user instead use `POST /channels/{id}/webhook`, which authorizes\nthrough channel membership. The bot owner is read from `GET /bots/me` and\ncached by the client.\n\nThe webhook endpoint supports content only. Mentions in `<m-*>` tags still\nwork, but threads and attachments are not supported.\n\nPosting to a `Thread` puts the message in that thread; to a `Channel`, at the\nchannel root. One target rather than a channel plus a thread id, so the two\ncan't disagree.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `target` | [`Channel`](../../channel/classes/Channel.md) \\| [`Thread`](../../thread/classes/Thread.md) |\n| `body` | [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) |\n\n## Returns\n\n`Promise`\\<`string`\\>\n\n\n<!-- src/entities/channels/thread/classes/Thread.md -->\n# Class: Thread\n\nA thread within a channel, rooted at a top-level message. Replies and\nthread-scoped posting live here.\n\n## Constructors\n\n### Constructor\n\n> **new Thread**(`client`, `channelId`, `rootId`): `Thread`\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | - |\n| `channelId` | `string` | - |\n| `rootId` | `string` | The id of the message this thread hangs off. |\n\n#### Returns\n\n`Thread`\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-channelid\"></a> `channelId` | `readonly` | `string` | - |\n| <a id=\"property-rootid\"></a> `rootId` | `readonly` | `string` | The id of the message this thread hangs off. |\n\n## Methods\n\n### channel()\n\n> **channel**(): [`Channel`](../../channel/classes/Channel.md)\n\nThe channel this thread is in.\n\n#### Returns\n\n[`Channel`](../../channel/classes/Channel.md)\n\n***\n\n### replies()\n\n> **replies**(): `Promise`\\<[`Message`](../../message/classes/Message.md)[]\\>\n\nList the replies in this thread, oldest first.\n\n#### Returns\n\n`Promise`\\<[`Message`](../../message/classes/Message.md)[]\\>\n\n***\n\n### reply()\n\n> **reply**(`body`): `Promise`\\<[`Message`](../../message/classes/Message.md)\\>\n\nPost a reply in this thread.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n\n#### Returns\n\n`Promise`\\<[`Message`](../../message/classes/Message.md)\\>\n\nThe created reply.\n\n***\n\n### root()\n\n> **root**(): [`Message`](../../message/classes/Message.md)\n\nThe message this thread hangs off.\n\n#### Returns\n\n[`Message`](../../message/classes/Message.md)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `channelId`: `string`; `rootId`: `string`; \\}\n\nSerialize the thread identity without its authenticated client.\n\n#### Returns\n\n\\{ `channelId`: `string`; `rootId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `channelId` | `string` |\n| `rootId` | `string` |\n"
},
- {
- "name": "chats",
- "description": "Read and send AI chat messages and stop generations.",
- "overview": "<!-- src/entities/chats/namespace/classes/ChatNamespace.md -->\n# Class: ChatNamespace\n\n## Constructors\n\n### Constructor\n\n> **new ChatNamespace**(`client`): `ChatNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`ChatNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Chat`](../../chat/classes/Chat.md)\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Chat`](../../chat/classes/Chat.md)\n\n***\n\n### create()\n\n> **create**(`opts?`): `Promise`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `name?`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name?` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n",
- "documentation": "# Macro SDK: chats\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/cognition/types.gen/type-aliases/AssistantMessagePart.md -->\n# Type Alias: AssistantMessagePart\n\n> **AssistantMessagePart** = \\{ `text`: `string`; `type`: `\"text\"`; \\} \\| \\{ `id`: `string`; `json`: `unknown`; `name`: `string`; `type`: `\"toolCall\"`; \\} \\| \\{ `display_name?`: `string` \\| `null`; `id`: `string`; `json`: `unknown`; `name`: `string`; `service`: `string`; `type`: `\"mcpToolCall\"`; \\} \\| \\{ `id`: `string`; `json`: `unknown`; `name`: `string`; `type`: `\"toolCallResponseJson\"`; \\} \\| \\{ `description`: `string`; `id`: `string`; `name`: `string`; `type`: `\"toolCallErr\"`; \\} \\| \\{ `thinking`: `string`; `type`: `\"thinking\"`; \\}\n\nA structured part within an assistant message.\n\nWhen the model responds with tool calls the full turn is persisted as a\nflat sequence of these parts. [`crate::convert::to_rig_messages`]\nreconstructs the turn boundaries that providers expect.\n\n## Union Members\n\n### Type Literal\n\n\\{ `text`: `string`; `type`: `\"text\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `text` | `string` | The text content. |\n| `type` | `\"text\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `json`: `unknown`; `name`: `string`; `type`: `\"toolCall\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | Provider-assigned call id. |\n| `json` | `unknown` | Tool arguments as JSON. |\n| `name` | `string` | Tool name. |\n| `type` | `\"toolCall\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `display_name?`: `string` \\| `null`; `id`: `string`; `json`: `unknown`; `name`: `string`; `service`: `string`; `type`: `\"mcpToolCall\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `display_name?` | `string` \\| `null` | Optional human-readable name. |\n| `id` | `string` | Provider-assigned call id. |\n| `json` | `unknown` | Tool arguments as JSON. |\n| `name` | `string` | Tool name. |\n| `service` | `string` | MCP service identifier. |\n| `type` | `\"mcpToolCall\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `json`: `unknown`; `name`: `string`; `type`: `\"toolCallResponseJson\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | Corresponding call id. |\n| `json` | `unknown` | Response payload. |\n| `name` | `string` | Tool name. |\n| `type` | `\"toolCallResponseJson\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `description`: `string`; `id`: `string`; `name`: `string`; `type`: `\"toolCallErr\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `description` | `string` | Human-readable error description. |\n| `id` | `string` | Corresponding call id. |\n| `name` | `string` | Tool name. |\n| `type` | `\"toolCallErr\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `thinking`: `string`; `type`: `\"thinking\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `thinking` | `string` | The thinking text content. |\n| `type` | `\"thinking\"` | - |\n\n\n<!-- generated/cognition/types.gen/type-aliases/ChatMessageContent.md -->\n# Type Alias: ChatMessageContent\n\n> **ChatMessageContent** = `string` \\| [`AssistantMessagePart`](AssistantMessagePart.md)[]\n\nThe content of a [`ChatMessage`].\n\nFor user and system messages the content is plain [`Text`](Self::Text).\nFor assistant messages it may additionally be a sequence of\n[`AssistantMessagePart`]s that encode tool-call round trips.\n\n\n<!-- generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md -->\n# Type Alias: ChatMessageWithAttachments\n\n> **ChatMessageWithAttachments** = \\{ `attachments`: [`Entity`](Entity.md)[]; `content`: [`ChatMessageContent`](ChatMessageContent.md); `id`: `string`; `role`: [`Role`](Role.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`Entity`](Entity.md)[] | The ids of the attachments used to generate the message |\n| <a id=\"property-content\"></a> `content` | [`ChatMessageContent`](ChatMessageContent.md) | Message content |\n| <a id=\"property-id\"></a> `id` | `string` | The chat message id |\n| <a id=\"property-role\"></a> `role` | [`Role`](Role.md) | Whether the chat is from the user or system |\n\n\n<!-- generated/cognition/types.gen/type-aliases/ChatResponse.md -->\n# Type Alias: ChatResponse\n\n> **ChatResponse** = \\{ `createdAt?`: `string` \\| `null`; `id`: `string`; `messages`: [`ChatMessageWithAttachments`](ChatMessageWithAttachments.md)[]; `model?`: `string` \\| `null`; `name`: `string`; `projectId?`: `string` \\| `null`; `updatedAt?`: `string` \\| `null`; `userId`: `string`; \\}\n\nThe full chat response, matching the DCS API response shape.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the chat was created. |\n| <a id=\"property-id\"></a> `id` | `string` | The chat uuid. |\n| <a id=\"property-messages\"></a> `messages` | [`ChatMessageWithAttachments`](ChatMessageWithAttachments.md)[] | The messages in the chat. |\n| <a id=\"property-model\"></a> `model?` | `string` \\| `null` | The model used to generate the chat (`provider/model` id). |\n| <a id=\"property-name\"></a> `name` | `string` | The name of the chat. |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | The project id the chat belongs to. |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the chat was last updated. |\n| <a id=\"property-userid\"></a> `userId` | `string` | Who the chat belongs to. |\n\n\n<!-- generated/cognition/types.gen/type-aliases/ConversationRecord.md -->\n# Type Alias: ConversationRecord\n\n> **ConversationRecord** = \\{ `chat_id`: `string`; `messages`: [`MessageWithAttachments`](MessageWithAttachments.md)[]; `title`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-chat_id\"></a> `chat_id` | `string` |\n| <a id=\"property-messages\"></a> `messages` | [`MessageWithAttachments`](MessageWithAttachments.md)[] |\n| <a id=\"property-title\"></a> `title` | `string` |\n\n\n<!-- generated/cognition/types.gen/type-aliases/Entity.md -->\n# Type Alias: Entity\n\n> **Entity** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); \\}\n\nThe Entity describes the minimum amount of information required to describe a unique thing in Macro\nThis contains the type of the entity [EntityType] and the string id of that entity\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | The id of that entity |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | The type of entity we are describing |\n\n\n<!-- generated/cognition/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"user\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"project\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"team\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"`\n\nThe type of an entity in Macro\n\n\n<!-- generated/cognition/types.gen/type-aliases/HttpSendChatMessageRequest.md -->\n# Type Alias: HttpSendChatMessageRequest\n\n> **HttpSendChatMessageRequest** = \\{ `additional_instructions?`: `string` \\| `null`; `attachments?`: [`Entity`](Entity.md)[] \\| `null`; `chat_id?`: `string` \\| `null`; `content`: `string`; `model`: `string`; `speed?`: [`ModelSpeed`](ModelSpeed.md); `toolset?`: [`ToolSet`](ToolSet.md); \\}\n\nHTTP request payload for sending a chat message.\nUnlike the WebSocket payload, this does not include stream_id as it's generated server-side.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additional_instructions\"></a> `additional_instructions?` | `string` \\| `null` | Additional system instructions appended to the base system prompt |\n| <a id=\"property-attachments\"></a> `attachments?` | [`Entity`](Entity.md)[] \\| `null` | Attachments for the message |\n| <a id=\"property-chat_id\"></a> `chat_id?` | `string` \\| `null` | Id of the chat the message belongs to (optional - if not provided, a new chat is created) |\n| <a id=\"property-content\"></a> `content` | `string` | The content of the message |\n| <a id=\"property-model\"></a> `model` | `string` | The model to respond with (`provider/model` id) |\n| <a id=\"property-speed\"></a> `speed?` | [`ModelSpeed`](ModelSpeed.md) | Inference speed, validated against the selected model. Defaults to standard. |\n| <a id=\"property-toolset\"></a> `toolset?` | [`ToolSet`](ToolSet.md) | Which toolset to use. Defaults to `all` |\n\n\n<!-- generated/cognition/types.gen/type-aliases/MessageWithAttachments.md -->\n# Type Alias: MessageWithAttachments\n\n> **MessageWithAttachments** = \\{ `attachmentIds`: `string`[]; `content`: `string`; `date`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-attachmentids\"></a> `attachmentIds` | `string`[] |\n| <a id=\"property-content\"></a> `content` | `string` |\n| <a id=\"property-date\"></a> `date` | `string` |\n\n\n<!-- generated/cognition/types.gen/type-aliases/ModelSpeed.md -->\n# Type Alias: ModelSpeed\n\n> **ModelSpeed** = `\"standard\"` \\| `\"fast\"` \\| `\"ultrafast\"`\n\nThe requested inference speed. Standard is backward compatible with old clients.\n\n\n<!-- generated/cognition/types.gen/type-aliases/Role.md -->\n# Type Alias: Role\n\n> **Role** = `\"user\"` \\| `\"assistant\"` \\| `\"system\"`\n\nThe role of a message participant.\n\n\n<!-- generated/cognition/types.gen/type-aliases/ToolSet.md -->\n# Type Alias: ToolSet\n\n> **ToolSet** = \\{ `type`: `\"all\"`; \\} \\| \\{ `type`: `\"none\"`; \\} \\| \\{ `type`: `\"databases\"`; \\} \\| \\{ `type`: `\"databases_read_only\"`; \\}\n\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/chats/chat/classes/Chat.md -->\n# Class: Chat\n\nA Macro AI chat.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`ChatDetail`\\>\n\n## Implements\n\n- [`Mentionable`](../../../../mentions/interfaces/Mentionable.md)\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the chat was created. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"chat\"` | `'chat'` | Favorites identify chats as `chat`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-messages\"></a> `messages` | `readonly` | () => `Promise`\\<[`ChatMessageWithAttachments`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md)[]\\> | `...` | The messages in the chat, with their attachments. | - | - |\n| <a id=\"property-model\"></a> `model` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The model used to generate the chat (`provider/model` id), if set. | - | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The chat's display name. | - | - |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this chat belongs to, if any. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the chat was last updated. | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Chat`\\> | `...` | Search chats by name and content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### copy()\n\n> **copy**(): `Promise`\\<`Chat`\\>\n\nCopy the chat, returning a handle to the new copy.\n\n#### Returns\n\n`Promise`\\<`Chat`\\>\n\n***\n\n### delete()\n\n> **delete**(`opts?`): `Promise`\\<`void`\\>\n\nDelete the chat. Soft by default (reversible with [restore](#restore));\npass `permanent: true` to delete irreversibly.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `permanent?`: `boolean`; \\} |\n| `opts.permanent?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Chat`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Chat`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### history()\n\n> **history**(): `Promise`\\<[`ConversationRecord`](../../../../../generated/cognition/types.gen/type-aliases/ConversationRecord.md)[]\\>\n\nThe chat's conversation history: titled records of messages with attachment ids.\n\n#### Returns\n\n`Promise`\\<[`ConversationRecord`](../../../../../generated/cognition/types.gen/type-aliases/ConversationRecord.md)[]\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the chat.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### restore()\n\n> **restore**(): `Promise`\\<`void`\\>\n\nRestore a soft-deleted chat.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### send()\n\n> **send**(`options`): `Promise`\\<[`ChatGeneration`](../../generation/classes/ChatGeneration.md)\\>\n\nSend a message and start a background generation. Tools may perform writes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`HttpSendChatMessageRequest`](../../../../../generated/cognition/types.gen/type-aliases/HttpSendChatMessageRequest.md), `\"chat_id\"` \\| `\"attachments\"` \\| `\"additional_instructions\"`\\> & \\{ `additionalInstructions?`: `string`; `attachments?`: [`EntityReference`](../../../reference/type-aliases/EntityReference.md)[]; \\} |\n\n#### Returns\n\n`Promise`\\<[`ChatGeneration`](../../generation/classes/ChatGeneration.md)\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ChatResponse`](../../../../../generated/cognition/types.gen/type-aliases/ChatResponse.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`ChatResponse`](../../../../../generated/cognition/types.gen/type-aliases/ChatResponse.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ChatResponse`](../../../../../generated/cognition/types.gen/type-aliases/ChatResponse.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Implementation of\n\n[`Mentionable`](../../../../mentions/interfaces/Mentionable.md).[`toMention`](../../../../mentions/interfaces/Mentionable.md#tomention)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Chat`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Chat`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe chat's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Chat`\n\nA handle to a chat by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Chat`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts?`): `Promise`\\<`Chat`\\>\n\nCreate a chat, optionally named and attached to a project.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | \\{ `name?`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name?` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Chat`\\>\n\n\n<!-- src/entities/chats/generation/classes/ChatGeneration.md -->\n# Class: ChatGeneration\n\nA background chat generation. The stream belongs to exactly one chat.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-chat\"></a> `chat` | `readonly` | [`Chat`](../../chat/classes/Chat.md) | Parent chat. |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | Stream identity. |\n| <a id=\"property-message\"></a> `message` | `readonly` | [`ChatMessage`](ChatMessage.md) | AI response message for this generation. |\n\n## Methods\n\n### stop()\n\n> **stop**(): `Promise`\\<`void`\\>\n\nRequest cancellation of this generation.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `chatId`: `string`; `id`: `string`; `messageId`: `string`; \\}\n\nSerialize scoped identity.\n\n#### Returns\n\n\\{ `chatId`: `string`; `id`: `string`; `messageId`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `chatId` | `string` |\n| `id` | `string` |\n| `messageId` | `string` |\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `chat`, `id`, `message`): `ChatGeneration`\n\nConstruct from a send receipt.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `chat` | [`Chat`](../../chat/classes/Chat.md) |\n| `id` | `string` |\n| `message` | [`ChatMessage`](ChatMessage.md) |\n\n#### Returns\n\n`ChatGeneration`\n\n\n<!-- src/entities/chats/generation/classes/ChatMessage.md -->\n# Class: ChatMessage\n\nA message scoped to an AI chat.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ChatMessageWithAttachments`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-chat\"></a> `chat` | `readonly` | [`Chat`](../../chat/classes/Chat.md) | Parent chat. | - |\n| <a id=\"property-content\"></a> `content` | `readonly` | () => `Promise`\\<[`ChatMessageContent`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageContent.md)\\> | The message's generated content. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-role\"></a> `role` | `readonly` | () => `Promise`\\<[`Role`](../../../../../generated/cognition/types.gen/type-aliases/Role.md)\\> | Role of the message author. | - |\n\n## Methods\n\n### refresh()\n\n> **refresh**(): `Promise`\\<`void`\\>\n\nReload after a running generation changes or finishes.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `chatId`: `string`; `detail?`: [`ChatMessageWithAttachments`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md); `id`: `string`; \\}\n\nSerialize scoped identity and any loaded message.\n\n#### Returns\n\n\\{ `chatId`: `string`; `detail?`: [`ChatMessageWithAttachments`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `chatId` | `string` |\n| `detail?` | [`ChatMessageWithAttachments`](../../../../../generated/cognition/types.gen/type-aliases/ChatMessageWithAttachments.md) |\n| `id` | `string` |\n\n#### Overrides\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `chat`, `id`): `ChatMessage`\n\nConstruct a chat message handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `chat` | [`Chat`](../../chat/classes/Chat.md) |\n| `id` | `string` |\n\n#### Returns\n\n`ChatMessage`\n\n\n<!-- src/entities/chats/namespace/classes/ChatNamespace.md -->\n# Class: ChatNamespace\n\n## Constructors\n\n### Constructor\n\n> **new ChatNamespace**(`client`): `ChatNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`ChatNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Chat`](../../chat/classes/Chat.md)\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Chat`](../../chat/classes/Chat.md)\n\n***\n\n### create()\n\n> **create**(`opts?`): `Promise`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `name?`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name?` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Chat`](../../chat/classes/Chat.md)\\>\n"
- },
{
"name": "crm",
"description": "Work with CRM records and pipeline tables, columns, rows and sharing.",
@@ -179,16 +173,10 @@
"overview": "<!-- src/entities/webhooks/namespace/classes/WebhooksNamespace.md -->\n# Class: WebhooksNamespace\n\nWebhook registrations for receiving signed entity-event deliveries.\n\n## Constructors\n\n### Constructor\n\n> **new WebhooksNamespace**(`client`): `WebhooksNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`WebhooksNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Webhook`](../../webhook/classes/Webhook.md)\n\nA handle to an existing webhook by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Webhook`](../../webhook/classes/Webhook.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)\\>\n\nRegister a webhook. `namespace` must be unique among the owning\nworkspace's webhooks (the endpoint returns 409 on a clash) and cannot be\nchanged later. `filters` must be non-empty (each entry matches event\nnames, optionally narrowed to entity ids); `scope` defaults to `'user'`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `filters`: [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[]; `headers?`: `Record`\\<`string`, `string`\\>; `name`: `string`; `namespace`: `string`; `scope?`: [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md); `url`: `string`; \\} |\n| `opts.filters` | [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] |\n| `opts.headers?` | `Record`\\<`string`, `string`\\> |\n| `opts.name` | `string` |\n| `opts.namespace` | `string` |\n| `opts.scope?` | [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md) |\n| `opts.url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)\\>\n\n***\n\n### list()\n\n> **list**(): `Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)[]\\>\n\nThe caller's webhooks across their personal and team workspaces, newest\nfirst. Each returned handle already holds its record.\n\n#### Returns\n\n`Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)[]\\>\n",
"documentation": "# Macro SDK: webhooks\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/storage/types.gen/type-aliases/BTreeMap.md -->\n# Type Alias: BTreeMap\n\n> **BTreeMap** = \\{\\[`key`: `string`\\]: `string`; \\}\n\n## Index Signature\n\n\\[`key`: `string`\\]: `string`\n\n\n<!-- generated/storage/types.gen/type-aliases/PatchWebhookRequest.md -->\n# Type Alias: PatchWebhookRequest\n\n> **PatchWebhookRequest** = \\{ `endpoint_url?`: `string` \\| `null`; `filters?`: `null` \\| [`Vec`](Vec.md); `headers?`: `null` \\| [`BTreeMap`](BTreeMap.md); `name?`: `string` \\| `null`; `status?`: `null` \\| [`WebhookStatus`](WebhookStatus.md); \\}\n\nRequest to patch a webhook. The webhook's namespace is fixed at creation\ntime and is deliberately not patchable.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-endpoint_url\"></a> `endpoint_url?` | `string` \\| `null` | Endpoint URL. HTTPS is required outside local environments. |\n| <a id=\"property-filters\"></a> `filters?` | `null` \\| [`Vec`](Vec.md) | - |\n| <a id=\"property-headers\"></a> `headers?` | `null` \\| [`BTreeMap`](BTreeMap.md) | - |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Display name. |\n| <a id=\"property-status\"></a> `status?` | `null` \\| [`WebhookStatus`](WebhookStatus.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/String.md -->\n# Type Alias: String\n\n> **String** = `string`\n\n\n<!-- generated/storage/types.gen/type-aliases/ValidateWebhookResponse.md -->\n# Type Alias: ValidateWebhookResponse\n\n> **ValidateWebhookResponse** = \\{ `is_valid`: `boolean`; `message?`: `string` \\| `null`; `response_status?`: `number` \\| `null`; `webhook_id`: [`String`](String.md); \\}\n\nSanitized result of validating a webhook endpoint.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-is_valid\"></a> `is_valid` | `boolean` | Whether the endpoint accepted the signed validation delivery. |\n| <a id=\"property-message\"></a> `message?` | `string` \\| `null` | Sanitized message explaining validation failure. |\n| <a id=\"property-response_status\"></a> `response_status?` | `number` \\| `null` | HTTP response status returned by the webhook endpoint, when available. |\n| <a id=\"property-webhook_id\"></a> `webhook_id` | [`String`](String.md) | Webhook id that was validated. |\n\n\n<!-- generated/storage/types.gen/type-aliases/Vec.md -->\n# Type Alias: Vec\n\n> **Vec** = \\{ `events`: `string`[]; `ids?`: `string`[] \\| `null`; \\}[]\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `events` | `string`[] | Event names matched by this filter. |\n| `ids?` | `string`[] \\| `null` | Entity ids matched by this filter. When absent, the filter matches all entity ids. |\n\n\n<!-- generated/storage/types.gen/type-aliases/Webhook.md -->\n# Type Alias: Webhook\n\n> **Webhook** = \\{ `created_at`: `string`; `created_by_user_id`: `string`; `deleted_at?`: `string` \\| `null`; `endpoint_url`: `string`; `filters`: [`Vec`](Vec.md); `headers`: [`BTreeMap`](BTreeMap.md); `id`: [`String`](String.md); `is_valid`: `boolean`; `name`: `string`; `namespace`: `string`; `status`: [`WebhookStatus`](WebhookStatus.md); `updated_at`: `string`; `workspace_id`: `string`; \\}\n\nWebhook row returned by application APIs.\n\nClients deserialize this, so both derives are used.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-created_by_user_id\"></a> `created_by_user_id` | `string` | User that created the webhook. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Soft-delete timestamp. |\n| <a id=\"property-endpoint_url\"></a> `endpoint_url` | `string` | Endpoint URL. HTTPS is required outside local environments. |\n| <a id=\"property-filters\"></a> `filters` | [`Vec`](Vec.md) | Typed filters used to match events and optional entity ids. |\n| <a id=\"property-headers\"></a> `headers` | [`BTreeMap`](BTreeMap.md) | Custom delivery headers, after decryption by the repository. |\n| <a id=\"property-id\"></a> `id` | [`String`](String.md) | Webhook id. |\n| <a id=\"property-is_valid\"></a> `is_valid` | `boolean` | Whether the current endpoint configuration has passed validation. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name. |\n| <a id=\"property-namespace\"></a> `namespace` | `string` | Caller-chosen namespace, unique among the owning workspace's webhooks. Set at creation time only; it cannot be changed afterwards. |\n| <a id=\"property-status\"></a> `status` | [`WebhookStatus`](WebhookStatus.md) | Webhook lifecycle status. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Update timestamp. |\n| <a id=\"property-workspace_id\"></a> `workspace_id` | `string` | Owning workspace id. |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookFilter.md -->\n# Type Alias: WebhookFilter\n\n> **WebhookFilter** = \\{ `events`: `string`[]; `ids?`: `string`[] \\| `null`; \\}\n\nEvent and optional entity-id constraints used to match webhook deliveries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-events\"></a> `events` | `string`[] | Event names matched by this filter. |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] \\| `null` | Entity ids matched by this filter. When absent, the filter matches all entity ids. |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookScope.md -->\n# Type Alias: WebhookScope\n\n> **WebhookScope** = `\"user\"` \\| `\"team\"`\n\nScope that owns a newly-created webhook.\n\nClients serialize this, so both derives are used. `Display`/`FromStr`\nspell the same names as serde, for query strings and config values.\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookStatus.md -->\n# Type Alias: WebhookStatus\n\n> **WebhookStatus** = `\"active\"` \\| `\"paused\"` \\| `\"disabled\"`\n\nWebhook lifecycle status.\n\n\n<!-- src/entities/webhooks/namespace/classes/WebhooksNamespace.md -->\n# Class: WebhooksNamespace\n\nWebhook registrations for receiving signed entity-event deliveries.\n\n## Constructors\n\n### Constructor\n\n> **new WebhooksNamespace**(`client`): `WebhooksNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`WebhooksNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Webhook`](../../webhook/classes/Webhook.md)\n\nA handle to an existing webhook by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Webhook`](../../webhook/classes/Webhook.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)\\>\n\nRegister a webhook. `namespace` must be unique among the owning\nworkspace's webhooks (the endpoint returns 409 on a clash) and cannot be\nchanged later. `filters` must be non-empty (each entry matches event\nnames, optionally narrowed to entity ids); `scope` defaults to `'user'`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `filters`: [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[]; `headers?`: `Record`\\<`string`, `string`\\>; `name`: `string`; `namespace`: `string`; `scope?`: [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md); `url`: `string`; \\} |\n| `opts.filters` | [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] |\n| `opts.headers?` | `Record`\\<`string`, `string`\\> |\n| `opts.name` | `string` |\n| `opts.namespace` | `string` |\n| `opts.scope?` | [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md) |\n| `opts.url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)\\>\n\n***\n\n### list()\n\n> **list**(): `Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)[]\\>\n\nThe caller's webhooks across their personal and team workspaces, newest\nfirst. Each returned handle already holds its record.\n\n#### Returns\n\n`Promise`\\<[`Webhook`](../../webhook/classes/Webhook.md)[]\\>\n\n\n<!-- src/entities/webhooks/webhook/classes/Webhook.md -->\n# Class: Webhook\n\nA webhook registration: an HTTPS endpoint Macro delivers signed entity\nevents to.\n\nA free-to-construct `(client, id)` handle like any other entity: the detail\nrecord loads lazily from the webhook GET endpoint on first field access and\nis dropped after any mutation. WebhooksNamespace.list enumerates the\ncaller's webhooks across their personal and team workspaces.\n\nThe signing secret is only ever returned once, from [create](#create); it's\nexposed there as [Webhook.signingSecret](#property-signingsecret). Save it — patches, gets,\nand `byId` handles never carry it again — and pass it to\n`MacroOpts.webhookSecret` so `macro.events.webhook()` can verify\ndeliveries. Live SSE via `macro.events.listen()` does not use a\npersisted webhook or signing secret.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Webhook`](../../../../../generated/storage/types.gen/type-aliases/Webhook.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the webhook was created. | - |\n| <a id=\"property-createdby\"></a> `createdBy` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | The user who registered this webhook. | - |\n| <a id=\"property-endpointurl\"></a> `endpointUrl` | `readonly` | () => `Promise`\\<`string`\\> | The HTTPS endpoint URL deliveries are sent to. | - |\n| <a id=\"property-filters\"></a> `filters` | `readonly` | () => `Promise`\\<[`Vec`](../../../../../generated/storage/types.gen/type-aliases/Vec.md)\\> | The event/entity-id filters that gate deliveries. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isvalid\"></a> `isValid` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the current endpoint configuration has passed validation. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | The webhook's display name. | - |\n| <a id=\"property-namespace\"></a> `namespace` | `readonly` | () => `Promise`\\<`string`\\> | The caller-chosen namespace, unique among the owning workspace's webhooks. Fixed at creation time; it cannot be patched. | - |\n| <a id=\"property-signingsecret\"></a> `signingSecret?` | `readonly` | `string` | The signing secret used to verify deliveries, present only on the handle returned by [create](#create). `undefined` for `byId` and listed handles. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`WebhookStatus`](../../../../../generated/storage/types.gen/type-aliases/WebhookStatus.md)\\> | The webhook's lifecycle status. | - |\n| <a id=\"property-workspaceid\"></a> `workspaceId` | `readonly` | () => `Promise`\\<`string`\\> | The owning workspace id: the creator's user id for a personal webhook, or a team id for a team webhook. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete the webhook.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### pause()\n\n> **pause**(): `Promise`\\<`void`\\>\n\nPause deliveries.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the webhook.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### resume()\n\n> **resume**(): `Promise`\\<`void`\\>\n\nResume deliveries.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### scope()\n\n> **scope**(): `Promise`\\<[`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md)\\>\n\nWhether this webhook is owned by the caller personally (`user`) or by\ntheir team (`team`). Derived from ownership: a personal webhook's owning\nworkspace is the creator's own user id, whereas a team webhook's workspace\nis a distinct team id.\n\n#### Returns\n\n`Promise`\\<[`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md)\\>\n\n***\n\n### setFilters()\n\n> **setFilters**(`filters`): `Promise`\\<`void`\\>\n\nReplace the webhook's delivery filters (must be non-empty).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `filters` | [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### setUrl()\n\n> **setUrl**(`url`): `Promise`\\<`void`\\>\n\nPoint the webhook at a new HTTPS endpoint URL.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Webhook`](../../../../../generated/storage/types.gen/type-aliases/Webhook.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Webhook`](../../../../../generated/storage/types.gen/type-aliases/Webhook.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Webhook`](../../../../../generated/storage/types.gen/type-aliases/Webhook.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### update()\n\n> **update**(`body`): `Promise`\\<`void`\\>\n\nUpdate the webhook.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | [`PatchWebhookRequest`](../../../../../generated/storage/types.gen/type-aliases/PatchWebhookRequest.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### validate()\n\n> **validate**(): `Promise`\\<[`ValidateWebhookResponse`](../../../../../generated/storage/types.gen/type-aliases/ValidateWebhookResponse.md)\\>\n\nSend a signed validation test delivery to the endpoint and report whether\nit was accepted. Drops the cached detail so a subsequent [isValid](#property-isvalid)\nread reflects the new validation state.\n\n#### Returns\n\n`Promise`\\<[`ValidateWebhookResponse`](../../../../../generated/storage/types.gen/type-aliases/ValidateWebhookResponse.md)\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Webhook`\n\nA handle to a webhook by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Webhook`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Webhook`\\>\n\nRegister a webhook.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `filters`: [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[]; `headers?`: `Record`\\<`string`, `string`\\>; `name`: `string`; `namespace`: `string`; `scope?`: [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md); `url`: `string`; \\} |\n| `opts.filters` | [`WebhookFilter`](../../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] |\n| `opts.headers?` | `Record`\\<`string`, `string`\\> |\n| `opts.name` | `string` |\n| `opts.namespace` | `string` |\n| `opts.scope?` | [`WebhookScope`](../../../../../generated/storage/types.gen/type-aliases/WebhookScope.md) |\n| `opts.url` | `string` |\n\n#### Returns\n\n`Promise`\\<`Webhook`\\>\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `record`): `Webhook`\n\nWrap an already-loaded record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `record` | [`Webhook`](../../../../../generated/storage/types.gen/type-aliases/Webhook.md) |\n\n#### Returns\n\n`Webhook`\n"
},
- {
- "name": "workspace",
- "description": "Browse recent workspace entities across documents, tasks, email, calendars, channels, calls, projects and chats with time, property, tag and inbox filters.",
- "overview": "<!-- src/entities/workspace/namespace/classes/WorkspaceNamespace.md -->\n# Class: WorkspaceNamespace\n\nBrowse recent workspace documents (including tasks), chats, projects, email,\nchannels, message threads, calls, calendar events and foreign entities.\nQueries run with the caller's normal access permissions. Use search namespaces\nto find specific names/content; use this namespace for activity and filtered lists.\n\nEach item has an existing `entity` handle plus a generated API `snapshot` for\nreading metadata without another request. Calendar snapshots contain event time\nand conference details; calendar handles support operations, but cannot fetch\nevent details by ID. Use `snapshot.data` when the listing already has your data.\n\n## Examples\n\n**Important emails from a particular accessible inbox**\n\n```js\nconst page = await macro.workspace.page({\n emailPreset: 'signal', inbox: '[email protected]', limit: 20,\n});\nconst evidence = page.items.map(item => ({\n id: item.id, ...item.type === 'email' ? {\n subject: item.subject, snippet: item.snippet, sender: item.senderEmail,\n } : {},\n}));\n// Report page.hasMore; this bounded page is not exhaustive.\n```\n\n**Tasks assigned to me, completed and updated within a time window**\n\n```js\nconst owner = await macro.myPrincipalId();\nconst tasks = macro.workspace.list({\n includeTypes: ['document'],\n df: {'&': [{l: {dst: 'task'}}, {'&': [\n {l: {ua: {gte: '2026-10-14T00:00:00Z'}}},\n {l: {ua: {lt: '2026-10-15T00:00:00Z'}}},\n ]}]},\n propf: {'&': [\n {l: {pd: '00000001-0000-0000-0000-000000000002', et: 'TASK',\n v: {so: '00000001-0000-0000-0002-000000000004'}}},\n {l: {pd: '00000001-0000-0000-0000-000000000001', et: 'TASK',\n v: {er: owner}}},\n ]},\n});\nfor await (const item of tasks) {\n if (item.type === 'document') console.log(item.id, item.name);\n}\n// updatedAt is not a completion timestamp; describe this scope accurately.\n```\n\n**Personal and team tags, favorites, and early stopping**\n\n```js\nlet count = 0;\nfor await (const item of macro.workspace.list({\n favoritesOnly: true, sortBy: 'recently_viewed',\n tags: [{label: 'Launch', scope: 'team'}], tagsMatch: 'all',\n})) {\n console.log(item.type, item.id, item.tags);\n if (++count === 10) break; // No subsequent page is fetched.\n}\n```\n\nA single filter is `{l: {dst: 'task'}}`; `&` and `|` require exactly two\nexpressions, nested for larger combinations.\nAdvanced filters use the normal API AST. `df` accepts `dst` (task/skill/snippet),\n`ft`, `id`, `pid`, and `ca`/`ua` timestamp bounds. `ef` supports `Sender`,\n`Recipient`, `Read`, `ThreadId`, `ca`/`ua`/`va`; `chanf` supports `ChannelId`,\n`Sender`, `IsParticipant`; `cthf` supports `ChannelId`/`ThreadId`; `callf`\nsupports `CallId`/`ChannelId`/`Speaker`/`Attended`. Filters remain server-validated.\nCRM, agent sessions, initiatives and database rows have their own namespaces\nand are not included in this browsing surface.\n\n## Constructors\n\n### Constructor\n\n> **new WorkspaceNamespace**(`client`): `WorkspaceNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`WorkspaceNamespace`\n\n## Methods\n\n### list()\n\n> **list**(`options?`): `AsyncGenerator`\\<[`WorkspaceItem`](../../types/type-aliases/WorkspaceItem.md)\\>\n\nLazy automatic pagination. `limit` is a page size, not a total result limit.\nBreak a `for await` loop to stop; no speculative next page is fetched.\nTag/inbox resolution is reused within this iterator.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`WorkspaceListOptions`](../../types/type-aliases/WorkspaceListOptions.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`WorkspaceItem`](../../types/type-aliases/WorkspaceItem.md)\\>\n\n***\n\n### page()\n\n> **page**(`options?`): `Promise`\\<[`WorkspacePage`](../../types/type-aliases/WorkspacePage.md)\\>\n\nOne bounded page. Resume using nextCursor and the same options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`WorkspacePageOptions`](../../types/type-aliases/WorkspacePageOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`WorkspacePage`](../../types/type-aliases/WorkspacePage.md)\\>\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceFilters.md -->\n# Type Alias: WorkspaceFilters\n\n> **WorkspaceFilters** = `Pick`\\<[`ApiEntityFilterAst`](../../../../../generated/storage/types.gen/type-aliases/ApiEntityFilterAst.md), `\"df\"` \\| `\"pf\"` \\| `\"cf\"` \\| `\"ef\"` \\| `\"chanf\"` \\| `\"cthf\"` \\| `\"callf\"` \\| `\"fef\"` \\| `\"calf\"` \\| `\"propf\"`\\>\n\nServer-validated AST filters, identical to the normal workspace API. Use\n`{l: literal}`, `{'&': [left, right]}`, `{'|': [left, right]}` or `{'!': expr}`.\n`&` and `|` require exactly two expressions; nest them for three or more.\nA single condition is `{l: literal}` without an `&` wrapper.\nEach entity filter applies only to that type; `propf` applies across types.\nSee WorkspaceNamespace for task and time-window examples.\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceItem.md -->\n# Type Alias: WorkspaceItem\n\n> **WorkspaceItem** = `Entry`\\<`\"document\"`, `\"document\"`, [`Document`](../../../documents/document/classes/Document.md)\\> & \\{ `fileType?`: `string` \\| `null`; `name`: `string`; `subType?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"chat\"`, `\"ai_chat\"`, [`Chat`](../../../chats/chat/classes/Chat.md)\\> & \\{ `name`: `string`; \\} \\| `Entry`\\<`\"project\"`, `\"project\"`, [`Project`](../../../projects/project/classes/Project.md)\\> & \\{ `name`: `string`; \\} \\| `Entry`\\<`\"emailThread\"`, `\"email\"`, [`EmailThread`](../../../email/thread/classes/EmailThread.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"emailThread\"`; \\}\\>\\[`\"data\"`\\], `\"snippet\"` \\| `\"senderName\"` \\| `\"senderEmail\"` \\| `\"inboxVisible\"` \\| `\"isRead\"` \\| `\"isDraft\"`\\> & \\{ `subject?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"channel\"`, `\"channel\"`, [`Channel`](../../../channels/channel/classes/Channel.md)\\> & \\{ `name?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"channelThread\"`, `\"channel_thread\"`, [`Thread`](../../../channels/thread/classes/Thread.md)\\> & \\{ `channelId`: `string`; \\} \\| `Entry`\\<`\"call\"`, `\"call\"`, [`CallRecord`](../../../calls/call-record/classes/CallRecord.md)\\> & \\{ `createdBy`: `string`; \\} \\| `Entry`\\<`\"calendarEvent\"`, `\"calendar_event\"`, [`CalendarEvent`](../../../calendar/event/classes/CalendarEvent.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"calendarEvent\"`; \\}\\>\\[`\"data\"`\\], `\"title\"` \\| `\"status\"` \\| `\"location\"` \\| `\"conferenceUrl\"` \\| `\"conferenceProvider\"` \\| `\"time\"`\\> \\| `Entry`\\<`\"foreignEntity\"`, `\"foreign_entity\"`, [`ForeignEntity`](../../../foreign/foreign-entity/classes/ForeignEntity.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"foreignEntity\"`; \\}\\>\\[`\"data\"`\\], `\"foreignEntityId\"` \\| `\"foreignEntitySource\"` \\| `\"metadata\"`\\>\n\nDiscriminated listing result. Read snapshot data without additional API calls.\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceListOptions.md -->\n# Type Alias: WorkspaceListOptions\n\n> **WorkspaceListOptions** = [`WorkspaceFilters`](WorkspaceFilters.md) & \\{ `emailPreset?`: `\"signal\"`; `emailView?`: `\"inbox\"` \\| `\"sent\"` \\| `\"drafts\"` \\| `\"starred\"` \\| `\"all\"` \\| `\"important\"` \\| `\"other\"` \\| `` `user:${string}` ``; `favoritesOnly?`: `boolean`; `inbox?`: `string`; `includeTypes?`: [`WorkspaceType`](WorkspaceType.md)[]; `limit?`: `number`; `sortBy?`: `\"recently_viewed\"` \\| `\"recently_updated\"` \\| `\"recently_created\"`; `tags?`: \\{ `label`: `string`; `scope?`: `\"personal\"` \\| `\"team\"`; \\}[]; `tagsMatch?`: `\"any\"` \\| `\"all\"`; \\}\n\nOptions shared by bounded pages and automatic iteration.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `emailPreset?` | `\"signal\"` | Important/signal email: overrides ef with Importance=true AND Shared=exclude. |\n| `emailView?` | `\"inbox\"` \\| `\"sent\"` \\| `\"drafts\"` \\| `\"starred\"` \\| `\"all\"` \\| `\"important\"` \\| `\"other\"` \\| `` `user:${string}` `` | Default inbox. Use signal + inbox for important emails, not the important view. |\n| `favoritesOnly?` | `boolean` | - |\n| `inbox?` | `string` | Connected inbox email address. Omit to include all accessible/delegated inboxes. |\n| `includeTypes?` | [`WorkspaceType`](WorkspaceType.md)[] | Omitted or empty means all supported types; signal defaults to email when omitted. |\n| `limit?` | `number` | Page size, default 50, clamped to 1–500. Iteration may fetch many pages. |\n| `sortBy?` | `\"recently_viewed\"` \\| `\"recently_updated\"` \\| `\"recently_created\"` | Defaults to recently_updated, descending. |\n| `tags?` | \\{ `label`: `string`; `scope?`: `\"personal\"` \\| `\"team\"`; \\}[] | Case-insensitive labels resolved against the caller's personal/team tags. |\n| `tagsMatch?` | `\"any\"` \\| `\"all\"` | Default any. All rejects ambiguous unscoped labels rather than guessing. |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspacePage.md -->\n# Type Alias: WorkspacePage\n\n> **WorkspacePage** = \\{ `hasMore`: `boolean`; `items`: [`WorkspaceItem`](WorkspaceItem.md)[]; `nextCursor?`: `string` \\| `null`; \\}\n\nA bounded page. A cursor means more results exist, not an exact total count.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-hasmore\"></a> `hasMore` | `boolean` |\n| <a id=\"property-items\"></a> `items` | [`WorkspaceItem`](WorkspaceItem.md)[] |\n| <a id=\"property-nextcursor\"></a> `nextCursor?` | `string` \\| `null` |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspacePageOptions.md -->\n# Type Alias: WorkspacePageOptions\n\n> **WorkspacePageOptions** = [`WorkspaceListOptions`](WorkspaceListOptions.md) & \\{ `cursor?`: `string`; \\}\n\nResume a page with its opaque cursor and the same options.\n\n## Type Declaration\n\n| Name | Type |\n| ------ | ------ |\n| `cursor?` | `string` |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceType.md -->\n# Type Alias: WorkspaceType\n\n> **WorkspaceType** = `\"calendar_event\"` \\| `\"document\"` \\| `\"ai_chat\"` \\| `\"project\"` \\| `\"email\"` \\| `\"channel\"` \\| `\"channel_thread\"` \\| `\"call\"` \\| `\"foreign_entity\"`\n\nWorkspace types supported by the browsing API. Tasks are documents.\n",
- "documentation": "# Macro SDK: workspace\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/storage/types.gen/type-aliases/AgentPullRequestState.md -->\n# Type Alias: AgentPullRequestState\n\n> **AgentPullRequestState** = `\"open\"` \\| `\"draft\"` \\| `\"closed\"` \\| `\"merged\"`\n\nLast synchronized state of a session's linked GitHub pull request.\n\n\n<!-- generated/storage/types.gen/type-aliases/ApiEntityFilterAst.md -->\n# Type Alias: ApiEntityFilterAst\n\n> **ApiEntityFilterAst** = \\{ `asf?`: `unknown`; `calf?`: `unknown`; `callf?`: `unknown`; `ccf?`: `unknown`; `cf?`: `unknown`; `chanf?`: `unknown`; `crma?`: `null` \\| [`CrmAssociation`](CrmAssociation.md); `crmf?`: `unknown`; `cthf?`: `unknown`; `df?`: `unknown`; `eca?`: `string`[]; `ecd?`: `string`[]; `ef?`: `unknown`; `favorites_only?`: `boolean` \\| `null`; `fef?`: `unknown`; `ghprf?`: `unknown`; `pf?`: `unknown`; `propf?`: `unknown`; \\}\n\nWire-format entity filter AST accepted by soup AST endpoints.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-asf\"></a> `asf?` | `unknown` | Filters applied to agent sessions (wire key `asf`). An empty or omitted filter returns **no** agent sessions: they are opt-in, so the caller must send `inc`, an id, or an owner to get any. |\n| <a id=\"property-calf\"></a> `calf?` | `unknown` | filters applied to canonical calendar events |\n| <a id=\"property-callf\"></a> `callf?` | `unknown` | the filters that should be applied to the call entity |\n| <a id=\"property-ccf\"></a> `ccf?` | `unknown` | Filters applied to the crm_company entity (wire key `ccf`). Empty/omitted = team's full visible list. |\n| <a id=\"property-cf\"></a> `cf?` | `unknown` | the filters that should be applied to the chat entity |\n| <a id=\"property-chanf\"></a> `chanf?` | `unknown` | the filters that should be applied to the channel entity |\n| <a id=\"property-crma\"></a> `crma?` | `null` \\| [`CrmAssociation`](CrmAssociation.md) | - |\n| <a id=\"property-crmf\"></a> `crmf?` | `unknown` | Opt-in filters for viewer-accessible CRM contacts (wire key `crmf`). |\n| <a id=\"property-cthf\"></a> `cthf?` | `unknown` | the filters that should be applied to the channel-thread entity |\n| <a id=\"property-df\"></a> `df?` | `unknown` | the filters that should be applied to the document entity |\n| <a id=\"property-eca\"></a> `eca?` | `string`[] | CRM-scoped address filter (wire key: `eca`). Symmetric counterpart to `ecd` for fully-qualified email addresses. |\n| <a id=\"property-ecd\"></a> `ecd?` | `string`[] | CRM-scoped domain filter (wire key: `ecd`). Parallel to the freeform `ef` AST. Expanded by the router into an any-direction OR sub-tree AND-merged into `ef`, plus a `CrmScope` tag stamped on the resulting [`item_filters::ast::EmailFilterAst::crm_scope`]. Drives the per-team CRM authorization pre-check and candidate-set widening downstream. Mutually exclusive with `eca`. |\n| <a id=\"property-ef\"></a> `ef?` | `unknown` | the filters that should be applied to the email entity (raw AST tree only; CRM scope is carried by the `ecd` / `eca` sibling fields). On this endpoint the email filter stays a bare tree, unlike the materialized [`EntityFilterAst`] used for cursors. |\n| <a id=\"property-favorites_only\"></a> `favorites_only?` | `boolean` \\| `null` | Restrict to the authenticated viewer's favorites before pagination when true. |\n| <a id=\"property-fef\"></a> `fef?` | `unknown` | the filters that should be applied to foreign entity records |\n| <a id=\"property-ghprf\"></a> `ghprf?` | `unknown` | the filters that should be applied to GitHub pull request records, on top of `fef` |\n| <a id=\"property-pf\"></a> `pf?` | `unknown` | the filters that should be applied to the project entity |\n| <a id=\"property-propf\"></a> `propf?` | `unknown` | the filters that should be applied based on entity properties |\n\n\n<!-- generated/storage/types.gen/type-aliases/CallStatus.md -->\n# Type Alias: CallStatus\n\n> **CallStatus** = `\"ATTENDED\"` \\| `\"MISSED\"` \\| `\"UNATTENDED\"`\n\nViewer-relative attendance status for a call record.\nSerializes as `ATTENDED`, `MISSED`, or `UNATTENDED`.\n\n\n<!-- generated/storage/types.gen/type-aliases/Channel.md -->\n# Type Alias: Channel\n\n> **Channel** = \\{ `channel_type`: [`ChannelType`](ChannelType.md); `created_at`: `string`; `id`: `string`; `name?`: `string` \\| `null`; `org_id?`: `number` \\| `null`; `owner_id`: `string`; `team_id?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nChannel metadata in soup payloads.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_type\"></a> `channel_type` | [`ChannelType`](ChannelType.md) | Channel type. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-id\"></a> `id` | `string` | Channel id. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Channel display name. |\n| <a id=\"property-org_id\"></a> `org_id?` | `number` \\| `null` | Organization id. |\n| <a id=\"property-owner_id\"></a> `owner_id` | `string` | Channel owner. |\n| <a id=\"property-team_id\"></a> `team_id?` | `string` \\| `null` | Team id. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Update timestamp. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelMessage.md -->\n# Type Alias: ChannelMessage\n\n> **ChannelMessage** = \\{ `content`: `string`; `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `mentions`: `string`[]; `message_id`: `string`; `sender_id`: `string`; `thread_id?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nLightweight channel message for soup payloads.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-content\"></a> `content` | `string` | Message content. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Deletion timestamp. |\n| <a id=\"property-mentions\"></a> `mentions` | `string`[] | Message mentions formatted as `{ENTITY_TYPE}:{ENTITY_ID}`. |\n| <a id=\"property-message_id\"></a> `message_id` | `string` | Message id. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Sender id. |\n| <a id=\"property-thread_id\"></a> `thread_id?` | `string` \\| `null` | Thread parent id. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Update timestamp. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelParticipant.md -->\n# Type Alias: ChannelParticipant\n\n> **ChannelParticipant** = \\{ `channel_id`: `string`; `joined_at`: `string`; `left_at?`: `string` \\| `null`; `role`: [`ParticipantRole`](ParticipantRole.md); `user_id`: `string`; \\}\n\nA user's membership in a channel.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id for the participant membership. |\n| <a id=\"property-joined_at\"></a> `joined_at` | `string` | Timestamp when the participant joined the channel. |\n| <a id=\"property-left_at\"></a> `left_at?` | `string` \\| `null` | Timestamp when the participant left the channel, if any. |\n| <a id=\"property-role\"></a> `role` | [`ParticipantRole`](ParticipantRole.md) | Participant role in the channel. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | Participant user id. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelType.md -->\n# Type Alias: ChannelType\n\n> **ChannelType** = `\"public\"` \\| `\"private\"` \\| `\"direct_message\"` \\| `\"team\"`\n\nType of channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelWithParticipants.md -->\n# Type Alias: ChannelWithParticipants\n\n> **ChannelWithParticipants** = \\{ `channel`: [`Channel`](Channel.md); `is_participant?`: `boolean`; `participants`: [`ChannelParticipant`](ChannelParticipant.md)[]; \\}\n\nChannel metadata together with its participants.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel\"></a> `channel` | [`Channel`](Channel.md) | Channel metadata. |\n| <a id=\"property-is_participant\"></a> `is_participant?` | `boolean` | Whether the requesting user is an active participant of the channel. False for team channels of the user's teams they have not joined. |\n| <a id=\"property-participants\"></a> `participants` | [`ChannelParticipant`](ChannelParticipant.md)[] | Participants in the channel. |\n\n\n<!-- generated/storage/types.gen/type-aliases/CrmAssociation.md -->\n# Type Alias: CrmAssociation\n\n> **CrmAssociation** = \\{ `company`: `string`; \\} \\| \\{ `contact`: `string`; \\}\n\nThe CRM record an association filter names.\n\n## Union Members\n\n### Type Literal\n\n\\{ `company`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `company` | `string` | Items associated with the company or with any of its contacts. |\n\n***\n\n### Type Literal\n\n\\{ `contact`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `contact` | `string` | Items associated with the contact. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/storage/types.gen/type-aliases/LatestMessage.md -->\n# Type Alias: LatestMessage\n\n> **LatestMessage** = \\{ `latest_message?`: `null` \\| [`ChannelMessage`](ChannelMessage.md); `latest_non_thread_message?`: `null` \\| [`ChannelMessage`](ChannelMessage.md); \\}\n\nLatest-message bundle for soup payloads.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-latest_message\"></a> `latest_message?` | `null` \\| [`ChannelMessage`](ChannelMessage.md) |\n| <a id=\"property-latest_non_thread_message\"></a> `latest_non_thread_message?` | `null` \\| [`ChannelMessage`](ChannelMessage.md) |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/storage/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupAgentSessionSoupPropertiesField.md -->\n# Type Alias: SoupAgentSessionSoupPropertiesField\n\n> **SoupAgentSessionSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `botId`: `string`; `createdAt`: `string`; `harness`: `string`; `id`: `string`; `isArchived`: `boolean`; `name`: `string`; `ownerId`: `string`; `pullRequestId?`: `string` \\| `null`; `pullRequestState?`: `null` \\| [`AgentPullRequestState`](AgentPullRequestState.md); `pullRequestUrl?`: `string` \\| `null`; `repoBranch?`: `string` \\| `null`; `repoUrl?`: `string` \\| `null`; `status`: `string`; `threadId?`: `string` \\| `null`; `turnState?`: `string` \\| `null`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; `workingBranch?`: `string` \\| `null`; \\}\n\nAn agent session as displayed in Soup.\n\nIncludes the persisted runtime and repository metadata needed to render\ncoding and non-coding sessions without fetching each session separately.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `botId` | `string` | The bot running this session |\n| `createdAt` | `string` | The time the session was created |\n| `harness` | `string` | The runtime snapshotted when the session was created. |\n| `id` | `string` | The agent session uuid |\n| `isArchived` | `boolean` | Whether the session is archived and read-only. |\n| `name` | `string` | The user-facing name of the session |\n| `ownerId` | `string` | Who the session belongs to |\n| `pullRequestId?` | `string` \\| `null` | The linked pull request's Macro entity, when visible to the viewer. |\n| `pullRequestState?` | `null` \\| [`AgentPullRequestState`](AgentPullRequestState.md) | - |\n| `pullRequestUrl?` | `string` \\| `null` | The persisted pull request associated with the session. |\n| `repoBranch?` | `string` \\| `null` | The starting branch selected for this session, not its current branch. |\n| `repoUrl?` | `string` \\| `null` | The repository the session works with, when one was selected. |\n| `status` | `string` | The session's last known status. `no_messages` until the first system event arrives, `disconnected` if the connection dropped without a clean close, otherwise the wire name of the most recent system event (for example `session/end`). |\n| `threadId?` | `string` \\| `null` | The channel thread the session was opened from, when any |\n| `turnState?` | `string` \\| `null` | Last persisted fold turn state. Absent until an older session next runs. |\n| `updatedAt` | `string` | The time the session was last modified |\n| `viewedAt?` | `string` \\| `null` | The time the session was last viewed by the requesting user |\n| `workingBranch?` | `string` \\| `null` | Last captured working branch, when the runtime has reported one. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupApiItem.md -->\n# Type Alias: SoupApiItem\n\n> **SoupApiItem** = [`SoupItem`](SoupItem.md) & \\{ `frecency_score`: `number`; `is_favorited`: `boolean`; `notified_at?`: `string` \\| `null`; `touched_at?`: `string` \\| `null`; \\}\n\nAPI representation of a soup item with its per-viewer enrichments.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `frecency_score` | `number` | - |\n| `is_favorited` | `boolean` | Whether the requesting user has favorited this entity. |\n| `notified_at?` | `string` \\| `null` | When the caller was last notified about this entity, present only when the page was ordered by `notified_at`. Clients keep the notified feed ordered and date-bucketed on this value. |\n| `touched_at?` | `string` \\| `null` | The caller's latest own mutation of this entity, present only when the page was ordered by `touched_by_me`. Clients keep the touched feed ordered on this value, so it can be bumped optimistically. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupAttachment.md -->\n# Type Alias: SoupAttachment\n\n> **SoupAttachment** = \\{ `contentId?`: `string` \\| `null`; `createdAt`: `string`; `filename?`: `string` \\| `null`; `id`: `string`; `messageId`: `string`; `mimeType?`: `string` \\| `null`; `providerAttachmentId?`: `string` \\| `null`; `sizeBytes?`: `number` \\| `null`; \\}\n\nAn email attachment as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-contentid\"></a> `contentId?` | `string` \\| `null` | Content id for inline attachments. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Timestamp when the attachment was created. |\n| <a id=\"property-filename\"></a> `filename?` | `string` \\| `null` | Attachment filename. |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment id. |\n| <a id=\"property-messageid\"></a> `messageId` | `string` | Message id that owns this attachment. |\n| <a id=\"property-mimetype\"></a> `mimeType?` | `string` \\| `null` | Attachment MIME type. |\n| <a id=\"property-providerattachmentid\"></a> `providerAttachmentId?` | `string` \\| `null` | Provider-specific attachment id. |\n| <a id=\"property-sizebytes\"></a> `sizeBytes?` | `number` \\| `null` | Attachment size in bytes. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCalendarEventSoupPropertiesField.md -->\n# Type Alias: SoupCalendarEventSoupPropertiesField\n\n> **SoupCalendarEventSoupPropertiesField** = \\{ `conferenceProvider?`: `string` \\| `null`; `conferenceUrl?`: `string` \\| `null`; `createdAt`: `string`; `description?`: `string` \\| `null`; `extra`: \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\}; `icalUid`: `string`; `id`: `string`; `isReadOnly`: `boolean`; `lastReminderFiredAt?`: `string` \\| `null`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `ownerId`: `string`; `status`: `string`; `time`: [`SoupCalendarEventTime`](SoupCalendarEventTime.md); `title`: `string`; `transparency`: `string`; `updatedAt`: `string`; `visibility`: `string`; \\}\n\nA canonical calendar event entity in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `string` \\| `null` | Which conferencing system backs `conference_url`. |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Direct conference join URL. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Entity creation timestamp. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional description. |\n| <a id=\"property-extra\"></a> `extra` | \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} | Property fields that can be flattened into property-bearing Soup items. |\n| `extra.properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n| <a id=\"property-icaluid\"></a> `icalUid` | `string` | RFC 5545 UID used for source reconciliation. |\n| <a id=\"property-id\"></a> `id` | `string` | Entity identifier. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the selected canonical source is read-only. |\n| <a id=\"property-lastreminderfiredat\"></a> `lastReminderFiredAt?` | `string` \\| `null` | When this event's most recent reminder notification was delivered. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional location label. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer email. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer display name. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Owning Macro user. |\n| <a id=\"property-status\"></a> `status` | `string` | Canonical status. |\n| <a id=\"property-time\"></a> `time` | [`SoupCalendarEventTime`](SoupCalendarEventTime.md) | Canonical master time. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | `string` | Availability transparency. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update timestamp. |\n| <a id=\"property-visibility\"></a> `visibility` | `string` | Canonical visibility. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCalendarEventTime.md -->\n# Type Alias: SoupCalendarEventTime\n\n> **SoupCalendarEventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nTimed or all-day calendar event span.\n\nFields are camelCased per variant rather than via `rename_all_fields`,\nwhich utoipa ignores — the generated OpenAPI schema would otherwise\nclaim snake_case fields the wire never carries.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start. |\n| `timeZone?` | `string` \\| `null` | Original IANA time zone. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive start date. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCallRecordGuest.md -->\n# Type Alias: SoupCallRecordGuest\n\n> **SoupCallRecordGuest** = \\{ `displayName`: `string`; `id`: `string`; `joinedAt`: `string`; `leftAt?`: `string` \\| `null`; \\}\n\nA non-account guest of a call record, as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-displayname\"></a> `displayName` | `string` | Guest-provided display name. |\n| <a id=\"property-id\"></a> `id` | `string` | Opaque guest identity; matches the guest's transcript speaker id. |\n| <a id=\"property-joinedat\"></a> `joinedAt` | `string` | When the guest joined the call. |\n| <a id=\"property-leftat\"></a> `leftAt?` | `string` \\| `null` | When the guest left (None if still in an active call). |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCallRecordParticipant.md -->\n# Type Alias: SoupCallRecordParticipant\n\n> **SoupCallRecordParticipant** = \\{ `joinedAt`: `string`; `leftAt?`: `string` \\| `null`; `userId`: `string`; \\}\n\nA Macro-account participant in a call record, as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-joinedat\"></a> `joinedAt` | `string` | When the user joined the call. |\n| <a id=\"property-leftat\"></a> `leftAt?` | `string` \\| `null` | When the user left (None if still in an active call). |\n| <a id=\"property-userid\"></a> `userId` | `string` | The Macro user id. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCallRecordSoupPropertiesField.md -->\n# Type Alias: SoupCallRecordSoupPropertiesField\n\n> **SoupCallRecordSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `attended`: `boolean`; `callId`: `string`; `channelId?`: `string` \\| `null`; `channelName?`: `string` \\| `null`; `createdBy`: `string`; `customName?`: `string` \\| `null`; `durationMs?`: `number` \\| `null`; `endedAt?`: `string` \\| `null`; `guests`: [`SoupCallRecordGuest`](SoupCallRecordGuest.md)[]; `isActive`: `boolean`; `participants`: [`SoupCallRecordParticipant`](SoupCallRecordParticipant.md)[]; `startedAt`: `string`; `status`: [`CallStatus`](CallStatus.md); `summary?`: `string` \\| `null`; \\}\n\nA call record as displayed in Soup. Excludes room_name, egress_id,\nand transcript — fields that are irrelevant for the soup feed.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `attended` | `boolean` | Whether the requesting user attended this call. Kept for compatibility and derived from `status == ATTENDED`. |\n| `callId` | `string` | The call identifier. |\n| `channelId?` | `string` \\| `null` | The channel this call belongs to. |\n| `channelName?` | `string` \\| `null` | Resolved display name for the channel. |\n| `createdBy` | `string` | User who created the call. |\n| `customName?` | `string` \\| `null` | User-supplied or AI-generated display name for the call. |\n| `durationMs?` | `number` \\| `null` | Call duration in milliseconds (None if still active). |\n| `endedAt?` | `string` \\| `null` | When the call ended (None if still active). |\n| `guests` | [`SoupCallRecordGuest`](SoupCallRecordGuest.md)[] | Non-account guests in the call. |\n| `isActive` | `boolean` | Whether the call is currently active. |\n| `participants` | [`SoupCallRecordParticipant`](SoupCallRecordParticipant.md)[] | Macro-account participants in the call. |\n| `startedAt` | `string` | When the call started. |\n| `status` | [`CallStatus`](CallStatus.md) | Viewer-relative call status for the requesting user. |\n| `summary?` | `string` \\| `null` | AI-generated summary of the call. Only set on archived `call_records` once summarization has run; active calls always return `None`. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupChannel.md -->\n# Type Alias: SoupChannel\n\n> **SoupChannel** = [`ChannelWithParticipants`](ChannelWithParticipants.md) & [`LatestMessage`](LatestMessage.md) & \\{ `interacted_at?`: `string` \\| `null`; `viewed_at?`: `string` \\| `null`; \\}\n\nA channel as displayed in Soup.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `interacted_at?` | `string` \\| `null` | Timestamp when the requesting user last interacted with this channel. |\n| `viewed_at?` | `string` \\| `null` | Timestamp when the requesting user last viewed this channel. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupChannelThread.md -->\n# Type Alias: SoupChannelThread\n\n> **SoupChannelThread** = \\{ `attachments`: [`SoupMessageAttachment`](SoupMessageAttachment.md)[]; `channel_id`: `string`; `content`: `string`; `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `edited_at?`: `string` \\| `null`; `id`: `string`; `reactions`: [`SoupCountedReaction`](SoupCountedReaction.md)[]; `sender`: [`SoupMessageSender`](SoupMessageSender.md); `sender_id`: `string`; `thread`: [`SoupThreadInfo`](SoupThreadInfo.md); `updated_at`: `string`; \\}\n\nA top-level channel message thread for soup payloads.\n\nThis mirrors the public channel-message API shape so soup consumers can\nrender a thread root the same way they render a channel timeline message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`SoupMessageAttachment`](SoupMessageAttachment.md)[] | Attachments on this message. |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | Channel id. |\n| <a id=\"property-content\"></a> `content` | `string` | Message content. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Deletion timestamp. |\n| <a id=\"property-edited_at\"></a> `edited_at?` | `string` \\| `null` | Edit timestamp. |\n| <a id=\"property-id\"></a> `id` | `string` | Message id. |\n| <a id=\"property-reactions\"></a> `reactions` | [`SoupCountedReaction`](SoupCountedReaction.md)[] | Reactions on this message. |\n| <a id=\"property-sender\"></a> `sender` | [`SoupMessageSender`](SoupMessageSender.md) | Structured sender identity. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Sender id. |\n| <a id=\"property-thread\"></a> `thread` | [`SoupThreadInfo`](SoupThreadInfo.md) | Thread metadata and preview replies. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Update timestamp. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupChatSoupPropertiesField.md -->\n# Type Alias: SoupChatSoupPropertiesField\n\n> **SoupChatSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `createdAt`: `string`; `deletedAt?`: `string` \\| `null`; `id`: `string`; `isPersistent`: `boolean`; `model?`: `string` \\| `null`; `name`: `string`; `ownerId`: `string`; `projectId?`: `string` \\| `null`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nA chat as displayed in Soup.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | The time the chat was created |\n| `deletedAt?` | `string` \\| `null` | The time the chat was deleted |\n| `id` | `string` | The chat uuid |\n| `isPersistent` | `boolean` | Whether the chat is persistent or not |\n| `model?` | `string` \\| `null` | The last model selected for a sent message (`provider/model` id). |\n| `name` | `string` | The name of the chat |\n| `ownerId` | `string` | Who the chat belongs to |\n| `projectId?` | `string` \\| `null` | The project id of the chat |\n| `updatedAt` | `string` | The time the chat was last updated |\n| `viewedAt?` | `string` \\| `null` | The time the chat was last viewed |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupContact.md -->\n# Type Alias: SoupContact\n\n> **SoupContact** = \\{ `emailAddress?`: `string` \\| `null`; `id`: `string`; `linkId`: `string`; `name?`: `string` \\| `null`; `sfsPhotoUrl?`: `string` \\| `null`; \\}\n\nA contact participating in an email thread as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emailaddress\"></a> `emailAddress?` | `string` \\| `null` | Contact email address. |\n| <a id=\"property-id\"></a> `id` | `string` | Contact id. |\n| <a id=\"property-linkid\"></a> `linkId` | `string` | Connected account link id for the contact. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Contact display name. |\n| <a id=\"property-sfsphotourl\"></a> `sfsPhotoUrl?` | `string` \\| `null` | Contact photo URL from SFS, if available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCountedReaction.md -->\n# Type Alias: SoupCountedReaction\n\n> **SoupCountedReaction** = \\{ `emoji`: `string`; `users`: `string`[]; \\}\n\nA reaction with emoji and user list.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emoji\"></a> `emoji` | `string` | Emoji string. |\n| <a id=\"property-users\"></a> `users` | `string`[] | User ids who added this reaction. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCrmCompanySoupPropertiesField.md -->\n# Type Alias: SoupCrmCompanySoupPropertiesField\n\n> **SoupCrmCompanySoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `createdAt`: `string`; `description?`: `string` \\| `null`; `domains`: [`SoupCrmDomain`](SoupCrmDomain.md)[]; `emailSync`: `boolean`; `hidden`: `boolean`; `id`: `string`; `name?`: `string` \\| `null`; `teamId`: `string`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nA CRM company as displayed in Soup. Carries the core company\nfields plus display metadata resolved from `crm_domain_directory`\nagainst the primary (earliest-created) domain.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | When the company was created. |\n| `description?` | `string` \\| `null` | Display description from the primary domain's directory entry. |\n| `domains` | [`SoupCrmDomain`](SoupCrmDomain.md)[] | Domains associated with this company, ordered by creation time ascending (primary first). |\n| `emailSync` | `boolean` | Whether email sync is enabled for this company. |\n| `hidden` | `boolean` | Whether the company is hidden from CRM listings. Soup filters these out by default. |\n| `id` | `string` | The id of the company. |\n| `name?` | `string` \\| `null` | Display name from the primary domain's directory entry, or `None` when unresolved. |\n| `teamId` | `string` | The id of the team that owns this company record. |\n| `updatedAt` | `string` | When the company was last updated. |\n| `viewedAt?` | `string` \\| `null` | When the requesting user last viewed this company, or `None` if never viewed. Mirrors the `viewed_at` other soup entities carry. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCrmContactSoupPropertiesField.md -->\n# Type Alias: SoupCrmContactSoupPropertiesField\n\n> **SoupCrmContactSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `companyId`: `string`; `companyName`: `string`; `createdAt`: `string`; `email`: `string`; `firstInteraction`: `string`; `hidden`: `boolean`; `id`: `string`; `lastInteraction`: `string`; `name?`: `string` \\| `null`; `teamId`: `string`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nOne original CRM contact record, selected from the viewer's accessible teams.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `companyId` | `string` | Parent company ID. |\n| `companyName` | `string` | Parent company's display name. |\n| `createdAt` | `string` | Record creation time. |\n| `email` | `string` | Full email address. |\n| `firstInteraction` | `string` | Earliest interaction for this team record. |\n| `hidden` | `boolean` | Whether the contact or parent company is hidden. |\n| `id` | `string` | Original team-owned contact ID. |\n| `lastInteraction` | `string` | Latest interaction for this team record. |\n| `name?` | `string` \\| `null` | Team-local display name, if known. |\n| `teamId` | `string` | Team owning this record. |\n| `updatedAt` | `string` | Record update time. |\n| `viewedAt?` | `string` \\| `null` | The viewer's latest visit to this record. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupCrmDomain.md -->\n# Type Alias: SoupCrmDomain\n\n> **SoupCrmDomain** = \\{ `companyId`: `string`; `createdAt`: `string`; `domain`: `string`; `id`: `string`; \\}\n\nA CRM domain as displayed in Soup. Mirrors the crm crate's\n[`CrmDomain`] with a stable wire shape that the FE can rely on.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-companyid\"></a> `companyId` | `string` | The id of the company the domain belongs to. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | When the domain record was created. |\n| <a id=\"property-domain\"></a> `domain` | `string` | The domain (lowercased, e.g. \"acme.com\"). |\n| <a id=\"property-id\"></a> `id` | `string` | The id of the domain record. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupDatabaseRowSoupPropertiesField.md -->\n# Type Alias: SoupDatabaseRowSoupPropertiesField\n\n> **SoupDatabaseRowSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `createdAt`: `string`; `createdBy?`: `string` \\| `null`; `databaseId`: `string`; `id`: `string`; `ownerId`: `string`; `position`: `string`; `tableId`: `string`; `updatedAt`: `string`; \\}\n\nA row of a Macro database table in the Soup feed. Its cells are its\nentity properties; access is its database's.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | Creation timestamp. |\n| `createdBy?` | `string` \\| `null` | Who created the row, when they still exist. |\n| `databaseId` | `string` | The database the table belongs to. |\n| `id` | `string` | Row identifier. |\n| `ownerId` | `string` | The database's owner, which owns every row in it. |\n| `position` | `string` | Fractional index ordering the row within its table. |\n| `tableId` | `string` | The table the row belongs to. |\n| `updatedAt` | `string` | Last modification timestamp. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupDocumentSoupPropertiesField.md -->\n# Type Alias: SoupDocumentSoupPropertiesField\n\n> **SoupDocumentSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt`: `string`; `deletedAt?`: `string` \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `id`: `string`; `name`: `string`; `ownerId`: `string`; `projectId?`: `string` \\| `null`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`SoupDocumentSubType`](SoupDocumentSubType.md); `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nA document as displayed in Soup.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| `createdAt` | `string` | The time the document was created |\n| `deletedAt?` | `string` \\| `null` | The time the document was deleted |\n| `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| `fileType?` | `string` \\| `null` | The file type of the document (e.g. pdf, docx) |\n| `id` | `string` | The document id |\n| `name` | `string` | The name of the document |\n| `ownerId` | `string` | The owner of the document |\n| `projectId?` | `string` \\| `null` | The id of the project that this document belongs to |\n| `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| `subType?` | `null` \\| [`SoupDocumentSubType`](SoupDocumentSubType.md) | - |\n| `updatedAt` | `string` | The time the document instance / document BOM was updated |\n| `viewedAt?` | `string` \\| `null` | The time the document was last viewed |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupDocumentSubType.md -->\n# Type Alias: SoupDocumentSubType\n\n> **SoupDocumentSubType** = \\{ `is_completed`: `boolean`; `type`: `\"task\"`; \\} \\| \\{ `type`: `\"snippet\"`; \\} \\| \\{ `type`: `\"skill\"`; \\} \\| \\{ `type`: `\"initiative_description\"`; \\}\n\nSub type of a document with associated properties encoded in each variant.\nThis ensures type-safety: task properties only exist when the document is a task.\n\n## Union Members\n\n### Type Literal\n\n\\{ `is_completed`: `boolean`; `type`: `\"task\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `is_completed` | `boolean` | Whether the task is completed. True if the Status property is set to \"Completed\". |\n| `type` | `\"task\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"snippet\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"skill\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"initiative_description\"`; \\}\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupEmailThreadPreview.md -->\n# Type Alias: SoupEmailThreadPreview\n\n> **SoupEmailThreadPreview** = \\{ `createdAt`: `string`; `id`: `string`; `inboxVisible`: `boolean`; `isDraft`: `boolean`; `isImportant`: `boolean`; `isRead`: `boolean`; `isSignal`: `boolean`; `name?`: `string` \\| `null`; `ownerId`: `string`; `projectId?`: `string` \\| `null`; `providerId?`: `string` \\| `null`; `senderEmail?`: `string` \\| `null`; `senderName?`: `string` \\| `null`; `senderPhotoUrl?`: `string` \\| `null`; `snippet?`: `string` \\| `null`; `sortTs`: `string`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nEmail thread preview data as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Timestamp when the thread was created. |\n| <a id=\"property-id\"></a> `id` | `string` | Thread id. |\n| <a id=\"property-inboxvisible\"></a> `inboxVisible` | `boolean` | Whether the thread should appear in the inbox. |\n| <a id=\"property-isdraft\"></a> `isDraft` | `boolean` | Whether the thread contains a draft. |\n| <a id=\"property-isimportant\"></a> `isImportant` | `boolean` | Whether the thread is marked important. |\n| <a id=\"property-isread\"></a> `isRead` | `boolean` | Whether the thread has been read. |\n| <a id=\"property-issignal\"></a> `isSignal` | `boolean` | The denormalized `email_threads.is_signal` importance classification — the same flag the soup Importance filter evaluates, distinct from `is_important` (Gmail's IMPORTANT label). |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Thread display name or subject. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Owner user id. |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | Project id associated with the thread. |\n| <a id=\"property-providerid\"></a> `providerId?` | `string` \\| `null` | Provider-specific thread id. |\n| <a id=\"property-senderemail\"></a> `senderEmail?` | `string` \\| `null` | Sender email address for the preview. |\n| <a id=\"property-sendername\"></a> `senderName?` | `string` \\| `null` | Sender display name for the preview. |\n| <a id=\"property-senderphotourl\"></a> `senderPhotoUrl?` | `string` \\| `null` | Sender photo URL for the preview. |\n| <a id=\"property-snippet\"></a> `snippet?` | `string` \\| `null` | Thread snippet. |\n| <a id=\"property-sortts\"></a> `sortTs` | `string` | Timestamp used for email thread sorting. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Timestamp when the thread was last updated. |\n| <a id=\"property-viewedat\"></a> `viewedAt?` | `string` \\| `null` | Timestamp when the requesting user last viewed the thread. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupEnrichedEmailThreadPreviewSoupPropertiesField.md -->\n# Type Alias: SoupEnrichedEmailThreadPreviewSoupPropertiesField\n\n> **SoupEnrichedEmailThreadPreviewSoupPropertiesField** = [`SoupEmailThreadPreview`](SoupEmailThreadPreview.md) & \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `attachments`: [`SoupAttachment`](SoupAttachment.md)[]; `labels`: [`SoupLabel`](SoupLabel.md)[]; `participants`: [`SoupContact`](SoupContact.md)[]; \\}\n\nEmail thread preview enriched with related metadata for Soup.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `attachments` | [`SoupAttachment`](SoupAttachment.md)[] | Attachments on the thread. |\n| `labels` | [`SoupLabel`](SoupLabel.md)[] | Labels attached to the thread. |\n| `participants` | [`SoupContact`](SoupContact.md)[] | Contacts participating in the thread. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupForeignEntity.md -->\n# Type Alias: SoupForeignEntity\n\n> **SoupForeignEntity** = \\{ `createdAt`: `string`; `foreignEntityId`: `string`; `foreignEntitySource`: `string`; `id`: `string`; `metadata`: \\{\\[`key`: `string`\\]: `unknown`; \\}; `storedForAuthEntity`: `string`; `storedForId`: `string`; `updatedAt`: `string`; \\}\n\nA foreign entity record as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Timestamp when the record was created. |\n| <a id=\"property-foreignentityid\"></a> `foreignEntityId` | `string` | Identifier assigned by the external system. |\n| <a id=\"property-foreignentitysource\"></a> `foreignEntitySource` | `string` | Source system that owns the external identifier. |\n| <a id=\"property-id\"></a> `id` | `string` | Internal primary key for this foreign entity record. |\n| <a id=\"property-metadata\"></a> `metadata` | \\{\\[`key`: `string`\\]: `unknown`; \\} | Arbitrary metadata stored with the mapping. |\n| <a id=\"property-storedforauthentity\"></a> `storedForAuthEntity` | `string` | Internal auth entity namespace this foreign entity is stored for. |\n| <a id=\"property-storedforid\"></a> `storedForId` | `string` | Internal entity identifier this foreign entity is stored for. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Timestamp when the record was last updated. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupInitiativeSoupPropertiesField.md -->\n# Type Alias: SoupInitiativeSoupPropertiesField\n\n> **SoupInitiativeSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `createdAt`: `string`; `id`: `string`; `name`: `string`; `ownerId`: `string`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nAn initiative (called a project in the frontend) in the Soup feed.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | Creation timestamp. |\n| `id` | `string` | Initiative identifier. |\n| `name` | `string` | Initiative display name. |\n| `ownerId` | `string` | Initiative owner. |\n| `updatedAt` | `string` | Last modification timestamp. |\n| `viewedAt?` | `string` \\| `null` | Last time the requesting user viewed the initiative. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupItem.md -->\n# Type Alias: SoupItem\n\n> **SoupItem** = \\{ `data`: [`SoupDocumentSoupPropertiesField`](SoupDocumentSoupPropertiesField.md); `tag`: `\"document\"`; \\} \\| \\{ `data`: [`SoupChatSoupPropertiesField`](SoupChatSoupPropertiesField.md); `tag`: `\"chat\"`; \\} \\| \\{ `data`: [`SoupProjectSoupPropertiesField`](SoupProjectSoupPropertiesField.md); `tag`: `\"project\"`; \\} \\| \\{ `data`: [`SoupInitiativeSoupPropertiesField`](SoupInitiativeSoupPropertiesField.md); `tag`: `\"initiative\"`; \\} \\| \\{ `data`: [`SoupEnrichedEmailThreadPreviewSoupPropertiesField`](SoupEnrichedEmailThreadPreviewSoupPropertiesField.md); `tag`: `\"emailThread\"`; \\} \\| \\{ `data`: [`SoupChannel`](SoupChannel.md); `tag`: `\"channel\"`; \\} \\| \\{ `data`: [`SoupChannelThread`](SoupChannelThread.md); `tag`: `\"channelThread\"`; \\} \\| \\{ `data`: [`SoupCallRecordSoupPropertiesField`](SoupCallRecordSoupPropertiesField.md); `tag`: `\"call\"`; \\} \\| \\{ `data`: [`SoupCalendarEventSoupPropertiesField`](SoupCalendarEventSoupPropertiesField.md); `tag`: `\"calendarEvent\"`; \\} \\| \\{ `data`: [`SoupCrmCompanySoupPropertiesField`](SoupCrmCompanySoupPropertiesField.md); `tag`: `\"crmCompany\"`; \\} \\| \\{ `data`: [`SoupCrmContactSoupPropertiesField`](SoupCrmContactSoupPropertiesField.md); `tag`: `\"crmContact\"`; \\} \\| \\{ `data`: [`SoupForeignEntity`](SoupForeignEntity.md); `tag`: `\"foreignEntity\"`; \\} \\| \\{ `data`: [`SoupAgentSessionSoupPropertiesField`](SoupAgentSessionSoupPropertiesField.md); `tag`: `\"agentSession\"`; \\} \\| \\{ `data`: [`SoupDatabaseRowSoupPropertiesField`](SoupDatabaseRowSoupPropertiesField.md); `tag`: `\"databaseRow\"`; \\}\n\nA single item in the Soup feed.\n\n## Union Members\n\n### Type Literal\n\n\\{ `data`: [`SoupDocumentSoupPropertiesField`](SoupDocumentSoupPropertiesField.md); `tag`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupDocumentSoupPropertiesField`](SoupDocumentSoupPropertiesField.md) | Document item. |\n| `tag` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupChatSoupPropertiesField`](SoupChatSoupPropertiesField.md); `tag`: `\"chat\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupChatSoupPropertiesField`](SoupChatSoupPropertiesField.md) | Chat item. |\n| `tag` | `\"chat\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupProjectSoupPropertiesField`](SoupProjectSoupPropertiesField.md); `tag`: `\"project\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupProjectSoupPropertiesField`](SoupProjectSoupPropertiesField.md) | Project item. |\n| `tag` | `\"project\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupInitiativeSoupPropertiesField`](SoupInitiativeSoupPropertiesField.md); `tag`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupInitiativeSoupPropertiesField`](SoupInitiativeSoupPropertiesField.md) | Initiative entity. |\n| `tag` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupEnrichedEmailThreadPreviewSoupPropertiesField`](SoupEnrichedEmailThreadPreviewSoupPropertiesField.md); `tag`: `\"emailThread\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupEnrichedEmailThreadPreviewSoupPropertiesField`](SoupEnrichedEmailThreadPreviewSoupPropertiesField.md) | Email thread item. |\n| `tag` | `\"emailThread\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupChannel`](SoupChannel.md); `tag`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupChannel`](SoupChannel.md) | Channel item. |\n| `tag` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupChannelThread`](SoupChannelThread.md); `tag`: `\"channelThread\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupChannelThread`](SoupChannelThread.md) | Channel thread item. |\n| `tag` | `\"channelThread\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupCallRecordSoupPropertiesField`](SoupCallRecordSoupPropertiesField.md); `tag`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupCallRecordSoupPropertiesField`](SoupCallRecordSoupPropertiesField.md) | Call record item. |\n| `tag` | `\"call\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupCalendarEventSoupPropertiesField`](SoupCalendarEventSoupPropertiesField.md); `tag`: `\"calendarEvent\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupCalendarEventSoupPropertiesField`](SoupCalendarEventSoupPropertiesField.md) | Calendar event item. |\n| `tag` | `\"calendarEvent\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupCrmCompanySoupPropertiesField`](SoupCrmCompanySoupPropertiesField.md); `tag`: `\"crmCompany\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupCrmCompanySoupPropertiesField`](SoupCrmCompanySoupPropertiesField.md) | CRM company item. |\n| `tag` | `\"crmCompany\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupCrmContactSoupPropertiesField`](SoupCrmContactSoupPropertiesField.md); `tag`: `\"crmContact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupCrmContactSoupPropertiesField`](SoupCrmContactSoupPropertiesField.md) | Team-owned CRM contact. |\n| `tag` | `\"crmContact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupForeignEntity`](SoupForeignEntity.md); `tag`: `\"foreignEntity\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupForeignEntity`](SoupForeignEntity.md) | Foreign entity item. |\n| `tag` | `\"foreignEntity\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupAgentSessionSoupPropertiesField`](SoupAgentSessionSoupPropertiesField.md); `tag`: `\"agentSession\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupAgentSessionSoupPropertiesField`](SoupAgentSessionSoupPropertiesField.md) | Agent session item. |\n| `tag` | `\"agentSession\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `data`: [`SoupDatabaseRowSoupPropertiesField`](SoupDatabaseRowSoupPropertiesField.md); `tag`: `\"databaseRow\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `data` | [`SoupDatabaseRowSoupPropertiesField`](SoupDatabaseRowSoupPropertiesField.md) | Database row item. |\n| `tag` | `\"databaseRow\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupLabel.md -->\n# Type Alias: SoupLabel\n\n> **SoupLabel** = \\{ `createdAt`: `string`; `id`: `string`; `labelListVisibility`: [`SoupLabelListVisibility`](SoupLabelListVisibility.md); `linkId`: `string`; `messageListVisibility`: [`SoupMessageListVisibility`](SoupMessageListVisibility.md); `name`: `string`; `providerLabelId`: `string`; `type`: [`SoupLabelType`](SoupLabelType.md); \\}\n\nAn email label as displayed in Soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Timestamp when the label was created. |\n| <a id=\"property-id\"></a> `id` | `string` | Label id. |\n| <a id=\"property-labellistvisibility\"></a> `labelListVisibility` | [`SoupLabelListVisibility`](SoupLabelListVisibility.md) | Label visibility in label lists. |\n| <a id=\"property-linkid\"></a> `linkId` | `string` | Connected account link id for the label. |\n| <a id=\"property-messagelistvisibility\"></a> `messageListVisibility` | [`SoupMessageListVisibility`](SoupMessageListVisibility.md) | Label visibility in message lists. |\n| <a id=\"property-name\"></a> `name` | `string` | Label display name. |\n| <a id=\"property-providerlabelid\"></a> `providerLabelId` | `string` | Provider-specific label id. |\n| <a id=\"property-type\"></a> `type` | [`SoupLabelType`](SoupLabelType.md) | Label type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupLabelListVisibility.md -->\n# Type Alias: SoupLabelListVisibility\n\n> **SoupLabelListVisibility** = `\"labelShow\"` \\| `\"labelShowIfUnread\"` \\| `\"labelHide\"`\n\nGmail-style label list visibility.\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupLabelType.md -->\n# Type Alias: SoupLabelType\n\n> **SoupLabelType** = `\"system\"` \\| `\"user\"`\n\nWhether an email label is provider-created or user-created.\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupMessageAttachment.md -->\n# Type Alias: SoupMessageAttachment\n\n> **SoupMessageAttachment** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: `string`; `height?`: `number` \\| `null`; `id`: `string`; `width?`: `number` \\| `null`; \\}\n\nAn attachment on a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity id. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Type of entity. |\n| <a id=\"property-height\"></a> `height?` | `number` \\| `null` | Height for images. |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment id. |\n| <a id=\"property-width\"></a> `width?` | `number` \\| `null` | Width for images. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupMessageListVisibility.md -->\n# Type Alias: SoupMessageListVisibility\n\n> **SoupMessageListVisibility** = `\"show\"` \\| `\"hide\"`\n\nGmail-style message list visibility for a label.\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupMessageSender.md -->\n# Type Alias: SoupMessageSender\n\n> **SoupMessageSender** = \\{ `avatar_url?`: `string` \\| `null`; `id`: `string`; `name?`: `string` \\| `null`; `type`: [`SoupMessageSenderType`](SoupMessageSenderType.md); \\}\n\nPublic sender identity for soup channel messages.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatar_url\"></a> `avatar_url?` | `string` \\| `null` | Avatar URL for bot senders. |\n| <a id=\"property-id\"></a> `id` | `string` | Sender id without the storage namespace prefix. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Display name for bot senders. |\n| <a id=\"property-type\"></a> `type` | [`SoupMessageSenderType`](SoupMessageSenderType.md) | Sender type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupMessageSenderType.md -->\n# Type Alias: SoupMessageSenderType\n\n> **SoupMessageSenderType** = `\"user\"` \\| `\"bot\"`\n\nPublic sender type for soup channel messages.\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupProjectSoupPropertiesField.md -->\n# Type Alias: SoupProjectSoupPropertiesField\n\n> **SoupProjectSoupPropertiesField** = \\{ `properties`: [`SoupProperty`](SoupProperty.md)[]; \\} & \\{ `createdAt`: `string`; `deletedAt?`: `string` \\| `null`; `id`: `string`; `name`: `string`; `ownerId`: `string`; `parentId?`: `string` \\| `null`; `updatedAt`: `string`; `viewedAt?`: `string` \\| `null`; \\}\n\nA project as displayed in Soup.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `properties` | [`SoupProperty`](SoupProperty.md)[] | Properties attached to the entity. |\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `createdAt` | `string` | The time the project was created |\n| `deletedAt?` | `string` \\| `null` | The time the project was deleted |\n| `id` | `string` | The id of the project |\n| `name` | `string` | The name of the project |\n| `ownerId` | `string` | The owner of the project |\n| `parentId?` | `string` \\| `null` | The parent project id |\n| `updatedAt` | `string` | The time the project was updated |\n| `viewedAt?` | `string` \\| `null` | The time the document was last viewed |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupProperty.md -->\n# Type Alias: SoupProperty\n\n> **SoupProperty** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `id`: `string`; `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nA property attached to a Soup item.\n\nThis is a simplified representation that includes only the definition and value,\nomitting the entity property assignment metadata and options.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) | The property definition |\n| <a id=\"property-id\"></a> `id` | `string` | Globally unique id of the assignment attaching this property to an entity. |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupThreadInfo.md -->\n# Type Alias: SoupThreadInfo\n\n> **SoupThreadInfo** = \\{ `latest_reply_at?`: `string` \\| `null`; `preview`: [`SoupThreadReply`](SoupThreadReply.md)[]; `reply_count`: `number`; \\}\n\nThread metadata and preview replies for soup channel messages.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-latest_reply_at\"></a> `latest_reply_at?` | `string` \\| `null` | Timestamp of the latest reply. |\n| <a id=\"property-preview\"></a> `preview` | [`SoupThreadReply`](SoupThreadReply.md)[] | Preview replies. |\n| <a id=\"property-reply_count\"></a> `reply_count` | `number` | Total reply count. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SoupThreadReply.md -->\n# Type Alias: SoupThreadReply\n\n> **SoupThreadReply** = \\{ `attachments`: [`SoupMessageAttachment`](SoupMessageAttachment.md)[]; `content`: `string`; `created_at`: `string`; `edited_at?`: `string` \\| `null`; `id`: `string`; `reactions`: [`SoupCountedReaction`](SoupCountedReaction.md)[]; `sender`: [`SoupMessageSender`](SoupMessageSender.md); `sender_id`: `string`; `updated_at`: `string`; \\}\n\nA thread reply shown in preview.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`SoupMessageAttachment`](SoupMessageAttachment.md)[] | Attachments on this reply. |\n| <a id=\"property-content\"></a> `content` | `string` | Reply content. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation timestamp. |\n| <a id=\"property-edited_at\"></a> `edited_at?` | `string` \\| `null` | Edit timestamp. |\n| <a id=\"property-id\"></a> `id` | `string` | Reply id. |\n| <a id=\"property-reactions\"></a> `reactions` | [`SoupCountedReaction`](SoupCountedReaction.md)[] | Reactions on this reply. |\n| <a id=\"property-sender\"></a> `sender` | [`SoupMessageSender`](SoupMessageSender.md) | Structured sender identity. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Sender id. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Update timestamp. |\n\n\n<!-- src/entities/workspace/namespace/classes/WorkspaceNamespace.md -->\n# Class: WorkspaceNamespace\n\nBrowse recent workspace documents (including tasks), chats, projects, email,\nchannels, message threads, calls, calendar events and foreign entities.\nQueries run with the caller's normal access permissions. Use search namespaces\nto find specific names/content; use this namespace for activity and filtered lists.\n\nEach item has an existing `entity` handle plus a generated API `snapshot` for\nreading metadata without another request. Calendar snapshots contain event time\nand conference details; calendar handles support operations, but cannot fetch\nevent details by ID. Use `snapshot.data` when the listing already has your data.\n\n## Examples\n\n**Important emails from a particular accessible inbox**\n\n```js\nconst page = await macro.workspace.page({\n emailPreset: 'signal', inbox: '[email protected]', limit: 20,\n});\nconst evidence = page.items.map(item => ({\n id: item.id, ...item.type === 'email' ? {\n subject: item.subject, snippet: item.snippet, sender: item.senderEmail,\n } : {},\n}));\n// Report page.hasMore; this bounded page is not exhaustive.\n```\n\n**Tasks assigned to me, completed and updated within a time window**\n\n```js\nconst owner = await macro.myPrincipalId();\nconst tasks = macro.workspace.list({\n includeTypes: ['document'],\n df: {'&': [{l: {dst: 'task'}}, {'&': [\n {l: {ua: {gte: '2026-10-14T00:00:00Z'}}},\n {l: {ua: {lt: '2026-10-15T00:00:00Z'}}},\n ]}]},\n propf: {'&': [\n {l: {pd: '00000001-0000-0000-0000-000000000002', et: 'TASK',\n v: {so: '00000001-0000-0000-0002-000000000004'}}},\n {l: {pd: '00000001-0000-0000-0000-000000000001', et: 'TASK',\n v: {er: owner}}},\n ]},\n});\nfor await (const item of tasks) {\n if (item.type === 'document') console.log(item.id, item.name);\n}\n// updatedAt is not a completion timestamp; describe this scope accurately.\n```\n\n**Personal and team tags, favorites, and early stopping**\n\n```js\nlet count = 0;\nfor await (const item of macro.workspace.list({\n favoritesOnly: true, sortBy: 'recently_viewed',\n tags: [{label: 'Launch', scope: 'team'}], tagsMatch: 'all',\n})) {\n console.log(item.type, item.id, item.tags);\n if (++count === 10) break; // No subsequent page is fetched.\n}\n```\n\nA single filter is `{l: {dst: 'task'}}`; `&` and `|` require exactly two\nexpressions, nested for larger combinations.\nAdvanced filters use the normal API AST. `df` accepts `dst` (task/skill/snippet),\n`ft`, `id`, `pid`, and `ca`/`ua` timestamp bounds. `ef` supports `Sender`,\n`Recipient`, `Read`, `ThreadId`, `ca`/`ua`/`va`; `chanf` supports `ChannelId`,\n`Sender`, `IsParticipant`; `cthf` supports `ChannelId`/`ThreadId`; `callf`\nsupports `CallId`/`ChannelId`/`Speaker`/`Attended`. Filters remain server-validated.\nCRM, agent sessions, initiatives and database rows have their own namespaces\nand are not included in this browsing surface.\n\n## Constructors\n\n### Constructor\n\n> **new WorkspaceNamespace**(`client`): `WorkspaceNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`WorkspaceNamespace`\n\n## Methods\n\n### list()\n\n> **list**(`options?`): `AsyncGenerator`\\<[`WorkspaceItem`](../../types/type-aliases/WorkspaceItem.md)\\>\n\nLazy automatic pagination. `limit` is a page size, not a total result limit.\nBreak a `for await` loop to stop; no speculative next page is fetched.\nTag/inbox resolution is reused within this iterator.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`WorkspaceListOptions`](../../types/type-aliases/WorkspaceListOptions.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`WorkspaceItem`](../../types/type-aliases/WorkspaceItem.md)\\>\n\n***\n\n### page()\n\n> **page**(`options?`): `Promise`\\<[`WorkspacePage`](../../types/type-aliases/WorkspacePage.md)\\>\n\nOne bounded page. Resume using nextCursor and the same options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`WorkspacePageOptions`](../../types/type-aliases/WorkspacePageOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`WorkspacePage`](../../types/type-aliases/WorkspacePage.md)\\>\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceFilters.md -->\n# Type Alias: WorkspaceFilters\n\n> **WorkspaceFilters** = `Pick`\\<[`ApiEntityFilterAst`](../../../../../generated/storage/types.gen/type-aliases/ApiEntityFilterAst.md), `\"df\"` \\| `\"pf\"` \\| `\"cf\"` \\| `\"ef\"` \\| `\"chanf\"` \\| `\"cthf\"` \\| `\"callf\"` \\| `\"fef\"` \\| `\"calf\"` \\| `\"propf\"`\\>\n\nServer-validated AST filters, identical to the normal workspace API. Use\n`{l: literal}`, `{'&': [left, right]}`, `{'|': [left, right]}` or `{'!': expr}`.\n`&` and `|` require exactly two expressions; nest them for three or more.\nA single condition is `{l: literal}` without an `&` wrapper.\nEach entity filter applies only to that type; `propf` applies across types.\nSee WorkspaceNamespace for task and time-window examples.\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceItem.md -->\n# Type Alias: WorkspaceItem\n\n> **WorkspaceItem** = `Entry`\\<`\"document\"`, `\"document\"`, [`Document`](../../../documents/document/classes/Document.md)\\> & \\{ `fileType?`: `string` \\| `null`; `name`: `string`; `subType?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"chat\"`, `\"ai_chat\"`, [`Chat`](../../../chats/chat/classes/Chat.md)\\> & \\{ `name`: `string`; \\} \\| `Entry`\\<`\"project\"`, `\"project\"`, [`Project`](../../../projects/project/classes/Project.md)\\> & \\{ `name`: `string`; \\} \\| `Entry`\\<`\"emailThread\"`, `\"email\"`, [`EmailThread`](../../../email/thread/classes/EmailThread.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"emailThread\"`; \\}\\>\\[`\"data\"`\\], `\"snippet\"` \\| `\"senderName\"` \\| `\"senderEmail\"` \\| `\"inboxVisible\"` \\| `\"isRead\"` \\| `\"isDraft\"`\\> & \\{ `subject?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"channel\"`, `\"channel\"`, [`Channel`](../../../channels/channel/classes/Channel.md)\\> & \\{ `name?`: `string` \\| `null`; \\} \\| `Entry`\\<`\"channelThread\"`, `\"channel_thread\"`, [`Thread`](../../../channels/thread/classes/Thread.md)\\> & \\{ `channelId`: `string`; \\} \\| `Entry`\\<`\"call\"`, `\"call\"`, [`CallRecord`](../../../calls/call-record/classes/CallRecord.md)\\> & \\{ `createdBy`: `string`; \\} \\| `Entry`\\<`\"calendarEvent\"`, `\"calendar_event\"`, [`CalendarEvent`](../../../calendar/event/classes/CalendarEvent.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"calendarEvent\"`; \\}\\>\\[`\"data\"`\\], `\"title\"` \\| `\"status\"` \\| `\"location\"` \\| `\"conferenceUrl\"` \\| `\"conferenceProvider\"` \\| `\"time\"`\\> \\| `Entry`\\<`\"foreignEntity\"`, `\"foreign_entity\"`, [`ForeignEntity`](../../../foreign/foreign-entity/classes/ForeignEntity.md)\\> & `Pick`\\<`Extract`\\<[`SoupApiItem`](../../../../../generated/storage/types.gen/type-aliases/SoupApiItem.md), \\{ `tag`: `\"foreignEntity\"`; \\}\\>\\[`\"data\"`\\], `\"foreignEntityId\"` \\| `\"foreignEntitySource\"` \\| `\"metadata\"`\\>\n\nDiscriminated listing result. Read snapshot data without additional API calls.\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceListOptions.md -->\n# Type Alias: WorkspaceListOptions\n\n> **WorkspaceListOptions** = [`WorkspaceFilters`](WorkspaceFilters.md) & \\{ `emailPreset?`: `\"signal\"`; `emailView?`: `\"inbox\"` \\| `\"sent\"` \\| `\"drafts\"` \\| `\"starred\"` \\| `\"all\"` \\| `\"important\"` \\| `\"other\"` \\| `` `user:${string}` ``; `favoritesOnly?`: `boolean`; `inbox?`: `string`; `includeTypes?`: [`WorkspaceType`](WorkspaceType.md)[]; `limit?`: `number`; `sortBy?`: `\"recently_viewed\"` \\| `\"recently_updated\"` \\| `\"recently_created\"`; `tags?`: \\{ `label`: `string`; `scope?`: `\"personal\"` \\| `\"team\"`; \\}[]; `tagsMatch?`: `\"any\"` \\| `\"all\"`; \\}\n\nOptions shared by bounded pages and automatic iteration.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `emailPreset?` | `\"signal\"` | Important/signal email: overrides ef with Importance=true AND Shared=exclude. |\n| `emailView?` | `\"inbox\"` \\| `\"sent\"` \\| `\"drafts\"` \\| `\"starred\"` \\| `\"all\"` \\| `\"important\"` \\| `\"other\"` \\| `` `user:${string}` `` | Default inbox. Use signal + inbox for important emails, not the important view. |\n| `favoritesOnly?` | `boolean` | - |\n| `inbox?` | `string` | Connected inbox email address. Omit to include all accessible/delegated inboxes. |\n| `includeTypes?` | [`WorkspaceType`](WorkspaceType.md)[] | Omitted or empty means all supported types; signal defaults to email when omitted. |\n| `limit?` | `number` | Page size, default 50, clamped to 1–500. Iteration may fetch many pages. |\n| `sortBy?` | `\"recently_viewed\"` \\| `\"recently_updated\"` \\| `\"recently_created\"` | Defaults to recently_updated, descending. |\n| `tags?` | \\{ `label`: `string`; `scope?`: `\"personal\"` \\| `\"team\"`; \\}[] | Case-insensitive labels resolved against the caller's personal/team tags. |\n| `tagsMatch?` | `\"any\"` \\| `\"all\"` | Default any. All rejects ambiguous unscoped labels rather than guessing. |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspacePage.md -->\n# Type Alias: WorkspacePage\n\n> **WorkspacePage** = \\{ `hasMore`: `boolean`; `items`: [`WorkspaceItem`](WorkspaceItem.md)[]; `nextCursor?`: `string` \\| `null`; \\}\n\nA bounded page. A cursor means more results exist, not an exact total count.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-hasmore\"></a> `hasMore` | `boolean` |\n| <a id=\"property-items\"></a> `items` | [`WorkspaceItem`](WorkspaceItem.md)[] |\n| <a id=\"property-nextcursor\"></a> `nextCursor?` | `string` \\| `null` |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspacePageOptions.md -->\n# Type Alias: WorkspacePageOptions\n\n> **WorkspacePageOptions** = [`WorkspaceListOptions`](WorkspaceListOptions.md) & \\{ `cursor?`: `string`; \\}\n\nResume a page with its opaque cursor and the same options.\n\n## Type Declaration\n\n| Name | Type |\n| ------ | ------ |\n| `cursor?` | `string` |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceTag.md -->\n# Type Alias: WorkspaceTag\n\n> **WorkspaceTag** = \\{ `label`: `string`; `scope`: `\"personal\"` \\| `\"team\"`; \\}\n\nA tag label visible to the caller, optionally qualified by ownership scope.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-label\"></a> `label` | `string` |\n| <a id=\"property-scope\"></a> `scope` | `\"personal\"` \\| `\"team\"` |\n\n\n<!-- src/entities/workspace/types/type-aliases/WorkspaceType.md -->\n# Type Alias: WorkspaceType\n\n> **WorkspaceType** = `\"calendar_event\"` \\| `\"document\"` \\| `\"ai_chat\"` \\| `\"project\"` \\| `\"email\"` \\| `\"channel\"` \\| `\"channel_thread\"` \\| `\"call\"` \\| `\"foreign_entity\"`\n\nWorkspace types supported by the browsing API. Tasks are documents.\n"
- },
{
"name": "core",
"description": "SDK construction, entity handles, lazy fields, search options, events and shared types.",
- "overview": "<!-- src/config/interfaces/MacroOpts.md -->\n# Interface: MacroOpts\n\nOptions passed to `new Macro(opts)` and stored on `MacroClient`.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-auth\"></a> `auth?` | [`MacroAuth`](../type-aliases/MacroAuth.md) | How to authenticate. Takes precedence over `token`. Falls back to `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN` (bot). |\n| <a id=\"property-env\"></a> `env?` | [`Env`](../type-aliases/Env.md) | Which Macro environment to talk to. Falls back to the MACRO_ENV env var, then `'prod'`. |\n| <a id=\"property-hosts\"></a> `hosts?` | `Partial`\\<`Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\> | Override individual service hosts (e.g. point one at localhost). |\n| <a id=\"property-onrequest\"></a> `onRequest?` | (`event`) => `void` | Optional generated API operation events; excludes arguments, URLs and response data. |\n| <a id=\"property-requestedas\"></a> `requestedAs?` | `string` | User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on every request. Bot auth only. Set via `macro.requestedAs(user)` rather than directly. |\n| <a id=\"property-token\"></a> `token?` | [`TokenSource`](../type-aliases/TokenSource.md) | Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API key (`mak_…`) or a bearer token. |\n| <a id=\"property-webappurl\"></a> `webAppUrl?` | `string` | Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. |\n| <a id=\"property-webhooksecret\"></a> `webhookSecret?` | `string` | Signing secret for verifying incoming persisted-webhook deliveries. Required only for `macro.events.webhook()` / `macro.events.handle()`. SSE via `macro.events.listen()` uses the API token and does not need this. Falls back to MACRO_WEBHOOK_SECRET. |\n| <a id=\"property-wsverify\"></a> `wsVerify?` | `string` | - |\n\n\n<!-- src/config/type-aliases/BotScope.md -->\n# Type Alias: BotScope\n\n> **BotScope** = `\"user\"` \\| `\"team\"`\n\nAccess scope for bot-authenticated requests. `user` acts with the\nrequested-as user's access (requires `requestedAs`); `team` acts with the\nbot's owning team's access (team-owned bots only).\n\n\n<!-- src/config/type-aliases/Env.md -->\n# Type Alias: Env\n\n> **Env** = `\"dev\"` \\| `\"prod\"` \\| `\"local\"`\n\n\n<!-- src/config/type-aliases/MacroAuth.md -->\n# Type Alias: MacroAuth\n\n> **MacroAuth** = \\{ `apiKey?`: `never`; `token`: [`TokenSource`](TokenSource.md); `type`: `\"user\"`; \\} \\| \\{ `apiKey`: `string`; `token?`: `never`; `type`: `\"user\"`; \\} \\| \\{ `scope?`: [`BotScope`](BotScope.md); `token`: [`TokenSource`](TokenSource.md); `type`: `\"bot\"`; \\}\n\nHow the SDK authenticates with Macro.\n\nA user has exactly one of two credential fields.\n\n- `token`: a bearer token, or a `mak_` API key. The SDK picks the header\n from the prefix at send time.\n- `apiKey`: a Settings → API Keys key, always sent as\n `x-macro-user-api-key`. Not prefix-checked, so keys that predate the\n `mak_` prefix work here.\n\nA bot uses an `mbot_` token as `x-macro-bot-token` plus\n`x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and\n`team` otherwise.\n\n\n<!-- src/config/type-aliases/ServiceName.md -->\n# Type Alias: ServiceName\n\n> **ServiceName** = `\"agent-harness\"` \\| `\"storage\"` \\| `\"auth\"` \\| `\"email\"` \\| `\"calendar\"` \\| `\"cognition\"` \\| `\"notification\"` \\| `\"properties\"` \\| `\"search\"` \\| `\"scheduled-action\"` \\| `\"static-files\"` \\| `\"connection\"` \\| `\"contacts\"` \\| `\"unfurl\"`\n\nThe backend services the SDK talks to. Note `search` and `properties` are\nserved on the storage host, so they point there.\n\n\n<!-- src/config/type-aliases/TokenSource.md -->\n# Type Alias: TokenSource\n\n> **TokenSource** = `string` \\| (() => `string` \\| `Promise`\\<`string`\\>)\n\nA credential string, or a (possibly async) function that returns one.\n\n\n<!-- src/config/variables/HOSTS.md -->\n# Variable: HOSTS\n\n> `const` **HOSTS**: `Record`\\<[`Env`](../type-aliases/Env.md), `Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\>\n\n\n<!-- src/config/variables/WEB_APP_URLS.md -->\n# Variable: WEB\\_APP\\_URLS\n\n> `const` **WEB\\_APP\\_URLS**: `Record`\\<[`Env`](../type-aliases/Env.md), `string`\\>\n\n\n<!-- src/macro/classes/Macro.md -->\n# Class: Macro\\<T\\>\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` *extends* [`MacroOpts`](../../config/interfaces/MacroOpts.md) | [`MacroOpts`](../../config/interfaces/MacroOpts.md) |\n\n## Constructors\n\n### Constructor\n\n> **new Macro**\\<`T`\\>(`opts`): `Macro`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | `T` |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-_client\"></a> `_client` | `readonly` | `MacroClient` | Direct access to the underlying hey-api service clients. |\n| <a id=\"property-agents\"></a> `agents` | `readonly` | [`AgentNamespace`](../../entities/agents/namespace/classes/AgentNamespace.md) | agents resources and operations. |\n| <a id=\"property-agentsessions\"></a> `agentSessions` | `readonly` | [`AgentSessionNamespace`](../../entities/agent-sessions/namespace/classes/AgentSessionNamespace.md) | - |\n| <a id=\"property-ai\"></a> `ai` | `readonly` | [`AiNamespace`](../../entities/ai/namespace/classes/AiNamespace.md) | - |\n| <a id=\"property-apikeys\"></a> `apiKeys` | `readonly` | [`ApiKeyNamespace`](../../entities/api-keys/namespace/classes/ApiKeyNamespace.md) | apiKeys resources and operations. |\n| <a id=\"property-bots\"></a> `bots` | `readonly` | [`BotsNamespace`](../../entities/bots/namespace/classes/BotsNamespace.md) | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | [`CalendarNamespace`](../../entities/calendar/namespace/classes/CalendarNamespace.md) | - |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | [`CallRecordNamespace`](../../entities/calls/namespace/classes/CallRecordNamespace.md) | - |\n| <a id=\"property-channels\"></a> `channels` | `readonly` | [`ChannelNamespace`](../../entities/channels/namespace/classes/ChannelNamespace.md) | - |\n| <a id=\"property-chats\"></a> `chats` | `readonly` | [`ChatNamespace`](../../entities/chats/namespace/classes/ChatNamespace.md) | - |\n| <a id=\"property-crm\"></a> `crm` | `readonly` | [`CrmNamespace`](../../entities/crm/namespace/classes/CrmNamespace.md) | - |\n| <a id=\"property-databases\"></a> `databases` | `readonly` | [`DatabaseNamespace`](../../entities/databases/namespace/classes/DatabaseNamespace.md) | - |\n| <a id=\"property-documents\"></a> `documents` | `readonly` | [`DocumentNamespace`](../../entities/documents/namespace/classes/DocumentNamespace.md) | - |\n| <a id=\"property-email\"></a> `email` | `readonly` | [`EmailNamespace`](../../entities/email/namespace/classes/EmailNamespace.md) | - |\n| <a id=\"property-entitymentions\"></a> `entityMentions` | `readonly` | [`EntityMentionNamespace`](../../entities/entity-mentions/namespace/classes/EntityMentionNamespace.md) | entityMentions resources and operations. |\n| <a id=\"property-events\"></a> `events` | `readonly` | [`MacroEvents`](../../events/receiver/classes/MacroEvents.md) | - |\n| <a id=\"property-favorites\"></a> `favorites` | `readonly` | [`FavoritesNamespace`](../../entities/favorites/namespace/classes/FavoritesNamespace.md) | - |\n| <a id=\"property-foreignentities\"></a> `foreignEntities` | `readonly` | [`ForeignEntityNamespace`](../../entities/foreign/namespace/classes/ForeignEntityNamespace.md) | - |\n| <a id=\"property-forms\"></a> `forms` | `readonly` | [`FormNamespace`](../../entities/forms/namespace/classes/FormNamespace.md) | Build forms and submit answers without granting respondents database access. |\n| <a id=\"property-githubpullrequests\"></a> `githubPullRequests` | `readonly` | [`GithubPullRequestNamespace`](../../entities/github-pull-requests/namespace/classes/GithubPullRequestNamespace.md) | githubPullRequests resources and operations. |\n| <a id=\"property-harnesses\"></a> `harnesses` | `readonly` | [`HarnessNamespace`](../../entities/harnesses/namespace/classes/HarnessNamespace.md) | harnesses resources and operations. |\n| <a id=\"property-initiatives\"></a> `initiatives` | `readonly` | [`InitiativeNamespace`](../../entities/initiatives/namespace/classes/InitiativeNamespace.md) | initiatives resources and operations. |\n| <a id=\"property-meetings\"></a> `meetings` | `readonly` | [`MeetingNamespace`](../../entities/meetings/namespace/classes/MeetingNamespace.md) | meetings resources and operations. |\n| <a id=\"property-notifications\"></a> `notifications` | `readonly` | [`NotificationNamespace`](../../entities/notifications/namespace/classes/NotificationNamespace.md) | - |\n| <a id=\"property-pins\"></a> `pins` | `readonly` | [`PinsNamespace`](../../entities/pins/namespace/classes/PinsNamespace.md) | - |\n| <a id=\"property-projects\"></a> `projects` | `readonly` | [`ProjectNamespace`](../../entities/projects/namespace/classes/ProjectNamespace.md) | - |\n| <a id=\"property-properties\"></a> `properties` | `readonly` | [`PropertiesNamespace`](../../entities/properties/namespace/classes/PropertiesNamespace.md) | - |\n| <a id=\"property-routines\"></a> `routines` | `readonly` | [`RoutineNamespace`](../../entities/routines/namespace/classes/RoutineNamespace.md) | routines resources and operations. |\n| <a id=\"property-tasks\"></a> `tasks` | `readonly` | [`TaskNamespace`](../../entities/tasks/namespace/classes/TaskNamespace.md) | - |\n| <a id=\"property-teams\"></a> `teams` | `readonly` | [`TeamNamespace`](../../entities/teams/namespace/classes/TeamNamespace.md) | - |\n| <a id=\"property-unfurls\"></a> `unfurls` | `readonly` | [`UnfurlNamespace`](../../entities/unfurls/namespace/classes/UnfurlNamespace.md) | unfurls resources and operations. |\n| <a id=\"property-users\"></a> `users` | `readonly` | [`UserNamespace`](../../entities/users/namespace/classes/UserNamespace.md) | - |\n| <a id=\"property-webappurl\"></a> `webAppUrl` | `readonly` | `string` | Base URL of the Macro web app, used to build entity URLs. |\n| <a id=\"property-webhooks\"></a> `webhooks` | `readonly` | [`WebhooksNamespace`](../../entities/webhooks/namespace/classes/WebhooksNamespace.md) | - |\n| <a id=\"property-workspace\"></a> `workspace` | `readonly` | [`WorkspaceNamespace`](../../entities/workspace/namespace/classes/WorkspaceNamespace.md) | Browse workspace activity with type, task, time, tag and inbox filters. |\n\n## Methods\n\n### myPrincipalId()\n\n> **myPrincipalId**(): `Promise`\\<`string`\\>\n\nThe authenticated caller's mentionable principal — `bot|<uuid>` for bot\nauth, `macro|<email>` for user auth — fetched once and cached.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### requestedAs()\n\n> **requestedAs**(`user`): `Macro`\\<`T`\\>\n\nClone of this SDK acting on behalf of `user` (sent as\n`x-macro-bot-for-macro-user-id`). Bot auth only — throws for user auth,\nsince a user token always acts as its own user.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../entities/users/user/classes/User.md) |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n\n<!-- src/macro/type-aliases/RequestActivity.md -->\n# Type Alias: RequestActivity\n\n> **RequestActivity** = \\{ `id`: `number`; `operation`: `string`; `service`: `string`; `status`: `\"started\"` \\| `\"completed\"` \\| `\"failed\"`; \\}\n\nA generated SDK operation lifecycle. Contains no arguments, URLs or response data.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-operation\"></a> `operation` | `string` |\n| <a id=\"property-service\"></a> `service` | `string` |\n| <a id=\"property-status\"></a> `status` | `\"started\"` \\| `\"completed\"` \\| `\"failed\"` |\n",
- "documentation": "# Macro SDK: core\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/search/types.gen/type-aliases/AgentSessionFilters.md -->\n# Type Alias: AgentSessionFilters\n\n> **AgentSessionFilters** = \\{ `ids?`: `string`[]; `include?`: `boolean`; `owners?`: `string`[]; \\}\n\nFilters for agent sessions.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] | Agent session ids to filter by. Empty to include all accessible sessions. |\n| <a id=\"property-include\"></a> `include?` | `boolean` | Opt this query into agent sessions at all. Agent sessions are off by default — see [`crate::ast::agent_session::AgentSessionLiteral::Include`]. Asking for specific `ids` or `owners` also opts in. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by session owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Empty to include every owner. |\n\n\n<!-- generated/search/types.gen/type-aliases/CalendarEventFilters.md -->\n# Type Alias: CalendarEventFilters\n\n> **CalendarEventFilters** = \\{ `attendees?`: `string`[]; `calendar_event_ids?`: `string`[]; `ends_after?`: `string` \\| `null`; `organizers?`: `string`[]; `starts_before?`: `string` \\| `null`; `statuses?`: `string`[]; \\}\n\nFilters for canonical calendar-event entities.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | `string`[] | Attendee email addresses. |\n| <a id=\"property-calendar_event_ids\"></a> `calendar_event_ids?` | `string`[] | Canonical event ids. |\n| <a id=\"property-ends_after\"></a> `ends_after?` | `string` \\| `null` | Include master events ending after this instant. |\n| <a id=\"property-organizers\"></a> `organizers?` | `string`[] | Organizer email addresses. |\n| <a id=\"property-starts_before\"></a> `starts_before?` | `string` \\| `null` | Include master events starting before this instant. |\n| <a id=\"property-statuses\"></a> `statuses?` | `string`[] | Event statuses such as `confirmed`, `tentative`, or `cancelled`. |\n\n\n<!-- generated/search/types.gen/type-aliases/CallFilters.md -->\n# Type Alias: CallFilters\n\n> **CallFilters** = \\{ `attended?`: `boolean` \\| `null`; `call_ids?`: `string`[]; `channel_ids?`: `string`[]; `speaker_ids?`: `string`[]; `status?`: `null` \\| [`CallStatus`](CallStatus.md); \\}\n\nFilters for call records.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attended\"></a> `attended?` | `boolean` \\| `null` | Legacy filter by whether the requesting user attended the call. Prefer [`CallFilters::status`] for new callers. `None` = no filter, `Some(true)` = only calls the user joined, `Some(false)` = only calls the user did not join. |\n| <a id=\"property-call_ids\"></a> `call_ids?` | `string`[] | Call record IDs to filter by. Empty to include all calls. |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs to filter calls by. Empty to include all calls. |\n| <a id=\"property-speaker_ids\"></a> `speaker_ids?` | `string`[] | Speaker macro user ids. Empty to include all. |\n| <a id=\"property-status\"></a> `status?` | `null` \\| [`CallStatus`](CallStatus.md) | - |\n\n\n<!-- generated/search/types.gen/type-aliases/CallStatus.md -->\n# Type Alias: CallStatus\n\n> **CallStatus** = `\"ATTENDED\"` \\| `\"MISSED\"` \\| `\"UNATTENDED\"`\n\nViewer-relative attendance status for a call record.\nSerializes as `ATTENDED`, `MISSED`, or `UNATTENDED`.\n\n\n<!-- generated/search/types.gen/type-aliases/ChannelFilters.md -->\n# Type Alias: ChannelFilters\n\n> **ChannelFilters** = \\{ `channel_ids?`: `string`[]; `channel_types?`: `string`[]; `importance?`: `boolean` \\| `null`; `is_participant?`: `boolean` \\| `null`; `mentions?`: `string`[]; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `org_id?`: `number` \\| `null`; `sender_ids?`: `string`[]; `team_id?`: `string` \\| `null`; `thread_ids?`: `string`[]; \\}\n\nThe channel message filters used to filter down what channel messages you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs to search within. Examples: ['general']. Empty to search all accessible channels. |\n| <a id=\"property-channel_types\"></a> `channel_types?` | `string`[] | Channel types to filter by. Examples: ['public'], ['direct_message', 'private']. Empty to search all channel types. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by channel importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-is_participant\"></a> `is_participant?` | `boolean` \\| `null` | Filter by whether the requesting user is an active participant of the channel. Presence of this filter also widens the candidate set to team channels of the user's teams that they have not joined, so `false` matches those channels. None to ignore (participant channels only, today's default). |\n| <a id=\"property-mentions\"></a> `mentions?` | `string`[] | Channel user mentions to search for. Examples: ['@username']. Empty if not filtering by mentions. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by channel notification state. |\n| <a id=\"property-org_id\"></a> `org_id?` | `number` \\| `null` | Channel organization ID to search within. Empty to ignore organization filtering. |\n| <a id=\"property-sender_ids\"></a> `sender_ids?` | `string`[] | Sender IDs to search within. Examples: ['user1']. Empty to search all accessible senders. |\n| <a id=\"property-team_id\"></a> `team_id?` | `string` \\| `null` | Channel team ID to search within. Empty to ignore team filtering. |\n| <a id=\"property-thread_ids\"></a> `thread_ids?` | `string`[] | Channel thread IDs to search within. Examples: ['thread123']. Empty to search all threads. |\n\n\n<!-- generated/search/types.gen/type-aliases/ChannelThreadFilters.md -->\n# Type Alias: ChannelThreadFilters\n\n> **ChannelThreadFilters** = \\{ `channel_ids?`: `string`[]; `participant_ids?`: `string`[]; `root_sender_ids?`: `string`[]; `thread_ids?`: `string`[]; \\}\n\nThe channel thread filters used to filter down channel-thread entities.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs containing the thread. Empty to include threads from all accessible channels. |\n| <a id=\"property-participant_ids\"></a> `participant_ids?` | `string`[] | Thread participant user IDs. A participant is the root message sender, anyone who replied in the thread, or anyone @-mentioned in the thread (group mentions like **Here** count through their per-user expansion at send time). Empty to include threads regardless of participants. |\n| <a id=\"property-root_sender_ids\"></a> `root_sender_ids?` | `string`[] | Sender IDs for the root thread message. Empty to include all root senders. |\n| <a id=\"property-thread_ids\"></a> `thread_ids?` | `string`[] | Channel thread parent message IDs to include. Empty to include all accessible threads. |\n\n\n<!-- generated/search/types.gen/type-aliases/ChatFilters.md -->\n# Type Alias: ChatFilters\n\n> **ChatFilters** = \\{ `chat_ids?`: `string`[]; `importance?`: `boolean` \\| `null`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; `role?`: `string`[]; \\}\n\nThe chat filters used to filter down what chats you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-chat_ids\"></a> `chat_ids?` | `string`[] | Chat ids to search over. Examples: ['chat1'], ['chat1', 'chat2']. When provided, chat search will only match results on these chats. Empty to search all accessible chats. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by chat importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by chat notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by chat owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Examples: ['project1']. Empty to ignore project filtering. |\n| <a id=\"property-role\"></a> `role?` | `string`[] | Chat message roles to search. Examples: ['user'], ['assistant']. Empty to search all roles. |\n\n\n<!-- generated/search/types.gen/type-aliases/CrmCompanyFilters.md -->\n# Type Alias: CrmCompanyFilters\n\n> **CrmCompanyFilters** = \\{ `company_ids?`: `string`[]; `hidden?`: `boolean` \\| `null`; \\}\n\nThe crm company filters used to narrow which CRM companies appear in soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-company_ids\"></a> `company_ids?` | `string`[] | CRM company ids to filter by. Examples: ['11111111-...']. Empty to include all of the team's visible CRM companies. |\n| <a id=\"property-hidden\"></a> `hidden?` | `boolean` \\| `null` | Optional `crm_companies.hidden` filter. `None` = visible only (default for back-compat with non-admin callers). `Some(false)` = visible only (explicit). `Some(true)` = hidden only — requires admin/owner team role; enforced by the CRM service from the caller's team receipt. |\n\n\n<!-- generated/search/types.gen/type-aliases/DocumentFilters.md -->\n# Type Alias: DocumentFilters\n\n> **DocumentFilters** = \\{ `document_ids?`: `string`[]; `file_types?`: `string`[]; `importance?`: `boolean` \\| `null`; `is_email_attachment?`: `boolean` \\| `null`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; `sub_types?`: `string`[]; `task_filters?`: [`TaskFilters`](TaskFilters.md); \\}\n\nThe document filters used to filter down what documents you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-document_ids\"></a> `document_ids?` | `string`[] | Document ids to search over. Examples: ['doc1'], ['doc1', 'doc2']. Empty to search all accessible documents. |\n| <a id=\"property-file_types\"></a> `file_types?` | `string`[] | Document file types to search. Examples: ['pdf'], ['md', 'txt']. Empty to search all file types. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by document importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-is_email_attachment\"></a> `is_email_attachment?` | `boolean` \\| `null` | Filter by email attachment status. true = only email attachments, false = only non-email attachments, None = both. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by document notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by document owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Examples: ['project1']. filtering. Empty to ignore project filtering. |\n| <a id=\"property-sub_types\"></a> `sub_types?` | `string`[] | Filter by document sub type. Examples: ['task']. Empty to search all sub types. |\n| <a id=\"property-task_filters\"></a> `task_filters?` | [`TaskFilters`](TaskFilters.md) | Task-specific filters that only apply to task subtype documents. |\n\n\n<!-- generated/search/types.gen/type-aliases/EmailFilters.md -->\n# Type Alias: EmailFilters\n\n> **EmailFilters** = \\{ `bcc?`: `string`[]; `calendar_only?`: `boolean` \\| `null`; `cc?`: `string`[]; `crm_addresses?`: `string`[]; `crm_domains?`: `string`[]; `email_thread_ids?`: `string`[]; `exclude_labels?`: `string`[]; `importance?`: `boolean` \\| `null`; `include_labels?`: `string`[]; `is_read?`: `boolean` \\| `null`; `link_ids?`: `string`[]; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `project_ids?`: `string`[]; `recipients?`: `string`[]; `senders?`: `string`[]; `shared?`: [`SharedEmailFilter`](SharedEmailFilter.md); \\}\n\nThe email filters used to filter down what emails you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | `string`[] | Email BCC addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by BCC. |\n| <a id=\"property-calendar_only\"></a> `calendar_only?` | `boolean` \\| `null` | When `Some(true)`, only include threads that have at least one message with an iCalendar attachment (`.ics` filename or `application/ics` mime type). `Some(false)` and `None` apply no constraint. |\n| <a id=\"property-cc\"></a> `cc?` | `string`[] | Email CC addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by CC. |\n| <a id=\"property-crm_addresses\"></a> `crm_addresses?` | `string`[] | CRM-scoped address filter. When non-empty, expands visibility to every teammate's mailbox and restricts to threads involving any of these fully-qualified addresses. Each address is authorized against `crm_contacts` + `crm_companies` (contact must not be hidden, company must not be hidden, `email_sync` must be true). Mutually exclusive with `crm_domains`. |\n| <a id=\"property-crm_domains\"></a> `crm_domains?` | `string`[] | CRM-scoped domain filter. When non-empty, expands visibility to every teammate's mailbox and restricts to threads involving any of these domains (in any of sender/cc/bcc/recipient). Each domain is authorized against `crm_domains` + `crm_companies` (must exist for the caller's team, company must not be hidden, `email_sync` must be true). Mutually exclusive with `crm_addresses`. |\n| <a id=\"property-email_thread_ids\"></a> `email_thread_ids?` | `string`[] | Email thread IDs to filter by. Examples: ['thread-uuid-1']. Empty to search all threads. |\n| <a id=\"property-exclude_labels\"></a> `exclude_labels?` | `string`[] | Exclude emails that have any of these labels. Supports both Gmail system labels (e.g. \"CATEGORY_PROMOTIONS\") and user-created labels. Empty to not exclude any labels. Note: SPAM and TRASH emails are not indexed in OpenSearch, so they are already excluded by default. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by email importance. None to not filter. True to show only important emails (drafts, personal, sent, or uncategorized). False to show only unimportant emails (those categorized as promotions, social, updates, or forums). |\n| <a id=\"property-include_labels\"></a> `include_labels?` | `string`[] | Only include emails that have at least one of these labels. Supports both Gmail system labels (e.g. \"INBOX\", \"CATEGORY_PROMOTIONS\") and user-created labels (e.g. \"github\"). Empty to not filter by included labels. Note: SPAM and TRASH emails are not indexed in OpenSearch, so they will never appear in results regardless of this filter. |\n| <a id=\"property-is_read\"></a> `is_read?` | `boolean` \\| `null` | Filter by the email thread's read flag, independently of notification state. |\n| <a id=\"property-link_ids\"></a> `link_ids?` | `string`[] | Restrict to specific inboxes by email_links.id. Empty means \"any inbox the caller can access\" (soup expands to the full set at the router edge). |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by email notification state. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Empty to ignore project filtering. |\n| <a id=\"property-recipients\"></a> `recipients?` | `string`[] | Email Recipient addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by Recipient. |\n| <a id=\"property-senders\"></a> `senders?` | `string`[] | Email sender addresses to filter by. Examples: ['[email protected]']. Empty to search all senders. |\n| <a id=\"property-shared\"></a> `shared?` | [`SharedEmailFilter`](SharedEmailFilter.md) | Controls whether shared email threads are included in results. Defaults to \"exclude\" (only the user's own threads). |\n\n\n<!-- generated/search/types.gen/type-aliases/EntityFilters.md -->\n# Type Alias: EntityFilters\n\n> **EntityFilters** = \\{ `agent_session_filters?`: [`AgentSessionFilters`](AgentSessionFilters.md); `calendar_event_filters?`: [`CalendarEventFilters`](CalendarEventFilters.md); `call_filters?`: [`CallFilters`](CallFilters.md); `channel_filters?`: [`ChannelFilters`](ChannelFilters.md); `channel_thread_filters?`: [`ChannelThreadFilters`](ChannelThreadFilters.md); `chat_filters?`: [`ChatFilters`](ChatFilters.md); `crm_company_filters?`: [`CrmCompanyFilters`](CrmCompanyFilters.md); `document_filters?`: [`DocumentFilters`](DocumentFilters.md); `email_filters?`: [`EmailFilters`](EmailFilters.md); `favorites_only?`: `boolean` \\| `null`; `foreign_entity_filters?`: [`ForeignEntityFilters`](ForeignEntityFilters.md); `initiative_filters?`: [`InitiativeFilters`](InitiativeFilters.md); `project_filters?`: [`ProjectFilters`](ProjectFilters.md); `property_filters?`: [`PropertyFilter`](PropertyFilter.md)[]; `tag_filter_mode?`: [`TagFilterMode`](TagFilterMode.md); `tag_option_ids?`: `string`[]; \\}\n\na bundle of all of the filters for each entity type\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-agent_session_filters\"></a> `agent_session_filters?` | [`AgentSessionFilters`](AgentSessionFilters.md) | the bundled [AgentSessionFilters] |\n| <a id=\"property-calendar_event_filters\"></a> `calendar_event_filters?` | [`CalendarEventFilters`](CalendarEventFilters.md) | the bundled [CalendarEventFilters] |\n| <a id=\"property-call_filters\"></a> `call_filters?` | [`CallFilters`](CallFilters.md) | the bundled [CallFilters] |\n| <a id=\"property-channel_filters\"></a> `channel_filters?` | [`ChannelFilters`](ChannelFilters.md) | the bundled [ChannelFilters] |\n| <a id=\"property-channel_thread_filters\"></a> `channel_thread_filters?` | [`ChannelThreadFilters`](ChannelThreadFilters.md) | the bundled [ChannelThreadFilters] |\n| <a id=\"property-chat_filters\"></a> `chat_filters?` | [`ChatFilters`](ChatFilters.md) | the bundled [ChatFilters] |\n| <a id=\"property-crm_company_filters\"></a> `crm_company_filters?` | [`CrmCompanyFilters`](CrmCompanyFilters.md) | the bundled [CrmCompanyFilters] |\n| <a id=\"property-document_filters\"></a> `document_filters?` | [`DocumentFilters`](DocumentFilters.md) | the bundled [DocumentFilters] |\n| <a id=\"property-email_filters\"></a> `email_filters?` | [`EmailFilters`](EmailFilters.md) | the bundled [EmailFilters] |\n| <a id=\"property-favorites_only\"></a> `favorites_only?` | `boolean` \\| `null` | Restrict results to the authenticated viewer's favorites when true. |\n| <a id=\"property-foreign_entity_filters\"></a> `foreign_entity_filters?` | [`ForeignEntityFilters`](ForeignEntityFilters.md) | the bundled [ForeignEntityFilters] |\n| <a id=\"property-initiative_filters\"></a> `initiative_filters?` | [`InitiativeFilters`](InitiativeFilters.md) | Initiative filters. Initiatives are opt-in. |\n| <a id=\"property-project_filters\"></a> `project_filters?` | [`ProjectFilters`](ProjectFilters.md) | the bundled [ProjectFilters] |\n| <a id=\"property-property_filters\"></a> `property_filters?` | [`PropertyFilter`](PropertyFilter.md)[] | property-based filters applied across entity types |\n| <a id=\"property-tag_filter_mode\"></a> `tag_filter_mode?` | [`TagFilterMode`](TagFilterMode.md) | How the `tag_option_ids` combine: `any` (default) matches entities holding at least one selected tag, `all` requires every selected tag. |\n| <a id=\"property-tag_option_ids\"></a> `tag_option_ids?` | `string`[] | tag option ids matched against `properties.values`, OR'd together across all tag definitions. Option ids are globally unique, so the match ignores the owning definition id (personal and team tags combine into one OR). |\n\n\n<!-- generated/search/types.gen/type-aliases/ForeignEntityFilters.md -->\n# Type Alias: ForeignEntityFilters\n\n> **ForeignEntityFilters** = \\{ `foreign_entity_ids?`: `string`[]; `foreign_entity_sources?`: `string`[]; `ids?`: `string`[]; `includes_me?`: `boolean`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); \\}\n\nFilters for foreign entity records.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-foreign_entity_ids\"></a> `foreign_entity_ids?` | `string`[] | External entity identifiers to filter by. Empty to include all external IDs. |\n| <a id=\"property-foreign_entity_sources\"></a> `foreign_entity_sources?` | `string`[] | External source names to filter by. Empty to include all sources. |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] | Internal foreign entity record IDs to filter by. Empty to include all records. |\n| <a id=\"property-includes_me\"></a> `includes_me?` | `boolean` | When true, only return foreign entities whose metadata lists the requesting user as a participant (GitHub `involves:me` semantics for `github_pull_request` records). False or absent applies no filter. Serialized in filter ASTs as the `\"me\"` literal. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by the notification state of the foreign entity (e.g. whether the requesting user's GitHub PR notification is done/seen). |\n\n\n<!-- generated/search/types.gen/type-aliases/InitiativeFilters.md -->\n# Type Alias: InitiativeFilters\n\n> **InitiativeFilters** = \\{ `due_after?`: `string` \\| `null`; `due_before?`: `string` \\| `null`; `include?`: `boolean`; `initiative_ids?`: `string`[]; `name?`: `string` \\| `null`; `owners?`: `string`[]; \\}\n\nFilters for initiatives.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-due_after\"></a> `due_after?` | `string` \\| `null` | Inclusive lower due-date bound. |\n| <a id=\"property-due_before\"></a> `due_before?` | `string` \\| `null` | Inclusive upper due-date bound. |\n| <a id=\"property-include\"></a> `include?` | `boolean` | Opt this query into initiatives at all. Initiatives are off by default — see [`crate::ast::initiative::InitiativeLiteral::Include`]. Asking for specific `initiative_ids` or `owners` also opts in. |\n| <a id=\"property-initiative_ids\"></a> `initiative_ids?` | `string`[] | Initiative ids to filter by. Empty to include all accessible initiatives. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Case-insensitive name substring. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by initiative owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Empty to include every owner. |\n\n\n<!-- generated/search/types.gen/type-aliases/NotificationFilters.md -->\n# Type Alias: NotificationFilters\n\n> **NotificationFilters** = \\{ `states?`: [`NotificationState`](NotificationState.md)[]; \\}\n\nNotification-level filters that apply to an entity type.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-states\"></a> `states?` | [`NotificationState`](NotificationState.md)[] | Include entities with a non-deleted notification in any of these exact states. Empty means no notification restriction. Active means `[unseen, seen]`. |\n\n\n<!-- generated/search/types.gen/type-aliases/NotificationState.md -->\n# Type Alias: NotificationState\n\n> **NotificationState** = `\"unseen\"` \\| `\"seen\"` \\| `\"done\"`\n\nThe mutually exclusive lifecycle states of a user's notification.\n\n\n<!-- generated/search/types.gen/type-aliases/ProjectFilters.md -->\n# Type Alias: ProjectFilters\n\n> **ProjectFilters** = \\{ `importance?`: `boolean` \\| `null`; `include_root?`: `boolean`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; \\}\n\nThe project filters used to filter down what projects you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by project importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-include_root\"></a> `include_root?` | `boolean` | When true, `project_ids` also matches the projects themselves in addition to their children. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by project notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by project owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | Project IDs to search within. Examples: ['project1']. Empty to search all accessible projects. By default matches children of these projects; set `include_root` to also match the projects themselves. |\n\n\n<!-- generated/search/types.gen/type-aliases/PropertyFilter.md -->\n# Type Alias: PropertyFilter\n\n> **PropertyFilter** = \\{ `entity_ids?`: `string`[]; `entity_type?`: `string` \\| `null`; `option_ids?`: `string`[]; `property_definition_id`: `string`; \\}\n\nA single property-based filter condition.\n\nEach filter targets a specific property definition on entities of a given type,\nmatching against select option UUIDs or entity reference IDs.\nMultiple values within a single filter are OR'd together.\nMultiple filters are AND'd together.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_ids\"></a> `entity_ids?` | `string`[] | Entity reference IDs to match. Multiple values are OR'd together. |\n| <a id=\"property-entity_type\"></a> `entity_type?` | `string` \\| `null` | The entity type for the property lookup (e.g., \"TASK\", \"DOCUMENT\", \"PROJECT\"). When None, matches across all entity types. |\n| <a id=\"property-option_ids\"></a> `option_ids?` | `string`[] | Select option UUIDs to match. Multiple values are OR'd together. |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` | The UUID of the property definition to filter on. |\n\n\n<!-- generated/search/types.gen/type-aliases/SharedEmailFilter.md -->\n# Type Alias: SharedEmailFilter\n\n> **SharedEmailFilter** = `\"exclude\"` \\| `\"include\"` \\| `\"only\"`\n\nControls whether shared email threads are included in results.\n\n\n<!-- generated/search/types.gen/type-aliases/TagFilterMode.md -->\n# Type Alias: TagFilterMode\n\n> **TagFilterMode** = `\"any\"` \\| `\"all\"`\n\nHow multiple `tag_option_ids` combine when filtering.\n\n\n<!-- generated/search/types.gen/type-aliases/TaskFilters.md -->\n# Type Alias: TaskFilters\n\n> **TaskFilters** = \\{ `include_cbm_atm_nc?`: `boolean` \\| `null`; \\}\n\nTask-only filters nested under document filters.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-include_cbm_atm_nc\"></a> `include_cbm_atm_nc?` | `boolean` \\| `null` | Include tasks that are created by me, assigned to me, and not completed, even when they do not match other document filters. |\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessRequest.md -->\n# Type Alias: AccessRequest\n\n> **AccessRequest** = \\{ `createdAt`: `string`; `grantedLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `id`: `string`; `requestedLevel`: [`AccessLevel`](AccessLevel.md); `requesterId`: `string`; `resolvedAt?`: `string` \\| `null`; `retryAfter?`: `string` \\| `null`; `revision`: `number`; `status`: [`RequestStatus`](RequestStatus.md); `updatedAt`: `string`; \\}\n\nLatest request for one person and one entity.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Start of this request attempt. |\n| <a id=\"property-grantedlevel\"></a> `grantedLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-id\"></a> `id` | `string` | Stable request identity across revisions. |\n| <a id=\"property-requestedlevel\"></a> `requestedLevel` | [`AccessLevel`](AccessLevel.md) | Requested upgrade. |\n| <a id=\"property-requesterid\"></a> `requesterId` | `string` | Person requesting access. |\n| <a id=\"property-resolvedat\"></a> `resolvedAt?` | `string` \\| `null` | When the request stopped being pending. |\n| <a id=\"property-retryafter\"></a> `retryAfter?` | `string` \\| `null` | Earliest next submission or level change; cancellation preserves this deadline. Submissions wait one minute, denials wait 24 hours, and approval clears it. |\n| <a id=\"property-revision\"></a> `revision` | `number` | Optimistic concurrency token. |\n| <a id=\"property-status\"></a> `status` | [`RequestStatus`](RequestStatus.md) | Current outcome. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Most recent change. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/FavoriteEntityRef.md -->\n# Type Alias: FavoriteEntityRef\n\n> **FavoriteEntityRef** = \\{ `entityId`: `string`; `entityType`: `\"user\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"project\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"team\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"`; \\}\n\nA reference to a favorited entity.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entityid\"></a> `entityId` | `string` | The id of the favorited entity. |\n| <a id=\"property-entitytype\"></a> `entityType` | `\"user\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"project\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"team\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | The type of the favorited entity. |\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageDirection.md -->\n# Type Alias: MessageDirection\n\n> **MessageDirection** = `\"older\"` \\| `\"newer\"`\n\nDirection through a parent timeline, retaining channel cursor semantics.\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/RequestStatus.md -->\n# Type Alias: RequestStatus\n\n> **RequestStatus** = `\"pending\"` \\| `\"granted\"` \\| `\"denied\"` \\| `\"cancelled\"`\n\nDurable outcome; reading a notification never changes it.\n\n\n<!-- generated/storage/types.gen/type-aliases/ResolveRequest.md -->\n# Type Alias: ResolveRequest\n\n> **ResolveRequest** = \\{ `grantedLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `revision`: `number`; \\}\n\nOwner's decision; omission of a granted level means deny.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-grantedlevel\"></a> `grantedLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-revision\"></a> `revision` | `number` | Request revision being reviewed. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ShareEntityType.md -->\n# Type Alias: ShareEntityType\n\n> **ShareEntityType** = `\"document\"` \\| `\"chat\"` \\| `\"project\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"call\"` \\| `\"email_thread\"` \\| `\"agent_session\"`\n\nAn entity type with an existing Share surface.\n\n\n<!-- generated/storage/types.gen/type-aliases/SimpleMention.md -->\n# Type Alias: SimpleMention\n\n> **SimpleMention** = \\{ `entity_id`: `string`; `entity_type`: `string`; \\}\n\nA mention tracked in a message body.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Mentioned entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Mentioned entity type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadAnchor.md -->\n# Type Alias: ThreadAnchor\n\n> **ThreadAnchor** = \\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\} \\| \\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\} \\| \\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\} \\| \\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\} \\| \\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\nA thread's location within its document. PDF geometry remains annotation-owned.\n\n## Union Members\n\n### Type Literal\n\n\\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `mark_id` | `string` | Mark UUID serialized in the document. |\n| `marked_text?` | `string` \\| `null` | The marked text as it read when the discussion was created, already trimmed and bounded. Absent on threads created or imported before snapshots were captured: the text a mark covers cannot be recovered from the mark id alone. |\n| `type` | `\"markdown\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Highlight annotation UUID. |\n| `marked_text?` | `string` \\| `null` | The text the highlight covers, trimmed and bounded like a markdown snapshot. The highlight owns it and it can be edited there, so it is read from the highlight whenever the thread is, never stored on the thread. Absent when the highlight carries no text. |\n| `type` | `\"pdf_highlight\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Placeable annotation UUID. |\n| `type` | `\"pdf_placeable\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `range` | `string` | A1 cell or range, such as B4 or B4:C9. |\n| `sheetId` | `string` | Stable sheet identity within the workbook. |\n| `sheetName` | `string` | Sheet name when the discussion was created. |\n| `type` | `\"spreadsheet\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `nodeId?` | `string` \\| `null` | Layer the pin follows; absent for a pin on the bare canvas. |\n| `pageId` | `string` | Page (canvas) the pin is on. |\n| `type` | `\"fig\"` | - |\n| `x` | `number` | Horizontal offset from the layer's origin, or the page's when the pin is on no layer, in design units. |\n| `y` | `number` | Vertical offset, measured like `x`. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadState.md -->\n# Type Alias: ThreadState\n\n> **ThreadState** = \\{ `anchor?`: `null` \\| [`ThreadAnchor`](ThreadAnchor.md); `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `resolved`: `boolean`; `root_id`: `string`; `updated_at`: `string`; `user_id`: `string`; \\}\n\nState belonging to a whole thread, keyed by its root message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-anchor\"></a> `anchor?` | `null` \\| [`ThreadAnchor`](ThreadAnchor.md) | - |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time of the discussion. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Explicit deletion of the entire thread, distinct from root deletion. |\n| <a id=\"property-resolved\"></a> `resolved` | `boolean` | Whether this discussion has been resolved. |\n| <a id=\"property-root_id\"></a> `root_id` | `string` | Root message UUID; there is no separate thread identity. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last state change. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User who owns this discussion, including imported discussions. |\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md -->\n# Type Alias: UpdateChannelSharePermission\n\n> **UpdateChannelSharePermission** = \\{ `accessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `channelId`: `string`; `operation`: [`UpdateOperation`](UpdateOperation.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-accesslevel\"></a> `accessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-channelid\"></a> `channelId` | `string` | The channel id |\n| <a id=\"property-operation\"></a> `operation` | [`UpdateOperation`](UpdateOperation.md) | The type of operation to be performed on the chanel share permission You can add, remove or replace and existing permission |\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateOperation.md -->\n# Type Alias: UpdateOperation\n\n> **UpdateOperation** = `\"add\"` \\| `\"remove\"` \\| `\"replace\"`\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md -->\n# Type Alias: UpdateSharePermissionRequestV2\n\n> **UpdateSharePermissionRequestV2** = \\{ `channelSharePermissions?`: [`UpdateChannelSharePermission`](UpdateChannelSharePermission.md)[] \\| `null`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`UpdateChannelSharePermission`](UpdateChannelSharePermission.md)[] \\| `null` | Any channel share permissions to be created/updated/removed |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookFilter.md -->\n# Type Alias: WebhookFilter\n\n> **WebhookFilter** = \\{ `events`: `string`[]; `ids?`: `string`[] \\| `null`; \\}\n\nEvent and optional entity-id constraints used to match webhook deliveries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-events\"></a> `events` | `string`[] | Event names matched by this filter. |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] \\| `null` | Entity ids matched by this filter. When absent, the filter matches all entity ids. |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookScope.md -->\n# Type Alias: WebhookScope\n\n> **WebhookScope** = `\"user\"` \\| `\"team\"`\n\nScope that owns a newly-created webhook.\n\nClients serialize this, so both derives are used. `Display`/`FromStr`\nspell the same names as serde, for query strings and config values.\n\n\n<!-- src/config/interfaces/MacroOpts.md -->\n# Interface: MacroOpts\n\nOptions passed to `new Macro(opts)` and stored on `MacroClient`.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-auth\"></a> `auth?` | [`MacroAuth`](../type-aliases/MacroAuth.md) | How to authenticate. Takes precedence over `token`. Falls back to `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN` (bot). |\n| <a id=\"property-env\"></a> `env?` | [`Env`](../type-aliases/Env.md) | Which Macro environment to talk to. Falls back to the MACRO_ENV env var, then `'prod'`. |\n| <a id=\"property-hosts\"></a> `hosts?` | `Partial`\\<`Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\> | Override individual service hosts (e.g. point one at localhost). |\n| <a id=\"property-onrequest\"></a> `onRequest?` | (`event`) => `void` | Optional generated API operation events; excludes arguments, URLs and response data. |\n| <a id=\"property-requestedas\"></a> `requestedAs?` | `string` | User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on every request. Bot auth only. Set via `macro.requestedAs(user)` rather than directly. |\n| <a id=\"property-token\"></a> `token?` | [`TokenSource`](../type-aliases/TokenSource.md) | Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API key (`mak_…`) or a bearer token. |\n| <a id=\"property-webappurl\"></a> `webAppUrl?` | `string` | Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. |\n| <a id=\"property-webhooksecret\"></a> `webhookSecret?` | `string` | Signing secret for verifying incoming persisted-webhook deliveries. Required only for `macro.events.webhook()` / `macro.events.handle()`. SSE via `macro.events.listen()` uses the API token and does not need this. Falls back to MACRO_WEBHOOK_SECRET. |\n| <a id=\"property-wsverify\"></a> `wsVerify?` | `string` | - |\n\n\n<!-- src/config/type-aliases/BotScope.md -->\n# Type Alias: BotScope\n\n> **BotScope** = `\"user\"` \\| `\"team\"`\n\nAccess scope for bot-authenticated requests. `user` acts with the\nrequested-as user's access (requires `requestedAs`); `team` acts with the\nbot's owning team's access (team-owned bots only).\n\n\n<!-- src/config/type-aliases/Env.md -->\n# Type Alias: Env\n\n> **Env** = `\"dev\"` \\| `\"prod\"` \\| `\"local\"`\n\n\n<!-- src/config/type-aliases/MacroAuth.md -->\n# Type Alias: MacroAuth\n\n> **MacroAuth** = \\{ `apiKey?`: `never`; `token`: [`TokenSource`](TokenSource.md); `type`: `\"user\"`; \\} \\| \\{ `apiKey`: `string`; `token?`: `never`; `type`: `\"user\"`; \\} \\| \\{ `scope?`: [`BotScope`](BotScope.md); `token`: [`TokenSource`](TokenSource.md); `type`: `\"bot\"`; \\}\n\nHow the SDK authenticates with Macro.\n\nA user has exactly one of two credential fields.\n\n- `token`: a bearer token, or a `mak_` API key. The SDK picks the header\n from the prefix at send time.\n- `apiKey`: a Settings → API Keys key, always sent as\n `x-macro-user-api-key`. Not prefix-checked, so keys that predate the\n `mak_` prefix work here.\n\nA bot uses an `mbot_` token as `x-macro-bot-token` plus\n`x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and\n`team` otherwise.\n\n\n<!-- src/config/type-aliases/ServiceName.md -->\n# Type Alias: ServiceName\n\n> **ServiceName** = `\"agent-harness\"` \\| `\"storage\"` \\| `\"auth\"` \\| `\"email\"` \\| `\"calendar\"` \\| `\"cognition\"` \\| `\"notification\"` \\| `\"properties\"` \\| `\"search\"` \\| `\"scheduled-action\"` \\| `\"static-files\"` \\| `\"connection\"` \\| `\"contacts\"` \\| `\"unfurl\"`\n\nThe backend services the SDK talks to. Note `search` and `properties` are\nserved on the storage host, so they point there.\n\n\n<!-- src/config/type-aliases/TokenSource.md -->\n# Type Alias: TokenSource\n\n> **TokenSource** = `string` \\| (() => `string` \\| `Promise`\\<`string`\\>)\n\nA credential string, or a (possibly async) function that returns one.\n\n\n<!-- src/config/variables/HOSTS.md -->\n# Variable: HOSTS\n\n> `const` **HOSTS**: `Record`\\<[`Env`](../type-aliases/Env.md), `Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\>\n\n\n<!-- src/config/variables/WEB_APP_URLS.md -->\n# Variable: WEB\\_APP\\_URLS\n\n> `const` **WEB\\_APP\\_URLS**: `Record`\\<[`Env`](../type-aliases/Env.md), `string`\\>\n\n\n<!-- src/entities/entity/classes/FavoritableEntity.md -->\n# Abstract Class: FavoritableEntity\\<Detail\\>\n\nAn entity the favorites API can address, and so can be (un)favorited.\n\n## Extends\n\n- [`MacroEntity`](MacroEntity.md)\\<`Detail`\\>\n\n## Extended by\n\n- [`CallRecord`](../../calls/call-record/classes/CallRecord.md)\n- [`Message`](../../channels/message/classes/Message.md)\n- [`Contact`](../../crm/contact/classes/Contact.md)\n- [`PropertiedEntity`](PropertiedEntity.md)\n- [`ForeignEntity`](../../foreign/foreign-entity/classes/ForeignEntity.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Implements\n\n- [`Favoritable`](../interfaces/Favoritable.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-entitytype\"></a> `entityType` | `abstract readonly` | `\"project\"` \\| `\"user\"` \\| `\"team\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | How the entity-addressed APIs (favorites) identify this entity's type. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](MacroEntity.md).[`id`](MacroEntity.md#property-id) |\n\n## Methods\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Favoritable`](../interfaces/Favoritable.md).[`favorite`](../interfaces/Favoritable.md#favorite)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](MacroEntity.md).[`toJSON`](MacroEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Favoritable`](../interfaces/Favoritable.md).[`unfavorite`](../interfaces/Favoritable.md#unfavorite)\n\n\n<!-- src/entities/entity/classes/MacroEntity.md -->\n# Abstract Class: MacroEntity\\<Detail\\>\n\nBase for entity handles: a free-to-construct `(client, id)` pair whose\ndetail record loads lazily on first field access and is dropped after any\nmutation. Subclasses implement fetch and build their surface from\nfield and mutate.\n\n## Extended by\n\n- [`AgentSession`](../../agent-sessions/agent-session/classes/AgentSession.md)\n- [`CodeExecution`](../../agent-sessions/code-execution/classes/CodeExecution.md)\n- [`SessionReview`](../../agent-sessions/review/classes/SessionReview.md)\n- [`Agent`](../../agents/agent/classes/Agent.md)\n- [`UserApiKey`](../../api-keys/api-key/classes/UserApiKey.md)\n- [`Calendar`](../../calendar/calendar/classes/Calendar.md)\n- [`CalendarEvent`](../../calendar/event/classes/CalendarEvent.md)\n- [`CallMessage`](../../calls/message/classes/CallMessage.md)\n- [`ChatMessage`](../../chats/generation/classes/ChatMessage.md)\n- [`CrmComment`](../../crm/comment/classes/CrmComment.md)\n- [`CrmPipeline`](../../crm/pipeline/classes/CrmPipeline.md)\n- [`PipelineTable`](../../crm/pipeline/classes/PipelineTable.md)\n- [`PipelineRow`](../../crm/pipeline/classes/PipelineRow.md)\n- [`PipelineColumn`](../../crm/pipeline/classes/PipelineColumn.md)\n- [`Database`](../../databases/database/classes/Database.md)\n- [`DocumentAnchor`](../../documents/anchor/classes/DocumentAnchor.md)\n- [`Comment`](../../documents/comment/classes/Comment.md)\n- [`EmailAttachment`](../../email/attachment/classes/EmailAttachment.md)\n- [`EmailFilter`](../../email/filter/classes/EmailFilter.md)\n- [`Label`](../../email/label/classes/Label.md)\n- [`Link`](../../email/link/classes/Link.md)\n- [`EmailMessage`](../../email/message/classes/EmailMessage.md)\n- [`FavoritableEntity`](FavoritableEntity.md)\n- [`Form`](../../forms/form/classes/Form.md)\n- [`GithubPullRequest`](../../github-pull-requests/pull-request/classes/GithubPullRequest.md)\n- [`Harness`](../../harnesses/harness/classes/Harness.md)\n- [`HarnessPairing`](../../harnesses/pairing/classes/HarnessPairing.md)\n- [`Initiative`](../../initiatives/initiative/classes/Initiative.md)\n- [`Meeting`](../../meetings/meeting/classes/Meeting.md)\n- [`MessageThread`](../../messages/thread/classes/MessageThread.md)\n- [`Notification`](../../notifications/notification/classes/Notification.md)\n- [`Routine`](../../routines/routine/classes/Routine.md)\n- [`AccessRequest`](../../sharing/access/classes/AccessRequest.md)\n- [`Team`](../../teams/team/classes/Team.md)\n- [`Webhook`](../../webhooks/webhook/classes/Webhook.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` |\n\n## Methods\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n\n<!-- src/entities/entity/classes/PropertiedEntity.md -->\n# Abstract Class: PropertiedEntity\\<Detail\\>\n\nA favoritable entity that also carries user-defined properties.\n\n## Extends\n\n- [`FavoritableEntity`](FavoritableEntity.md)\\<`Detail`\\>\n\n## Extended by\n\n- [`Channel`](../../channels/channel/classes/Channel.md)\n- [`Chat`](../../chats/chat/classes/Chat.md)\n- [`Company`](../../crm/company/classes/Company.md)\n- [`Document`](../../documents/document/classes/Document.md)\n- [`EmailThread`](../../email/thread/classes/EmailThread.md)\n- [`Project`](../../projects/project/classes/Project.md)\n- [`User`](../../users/user/classes/User.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Implements\n\n- [`Propertied`](../interfaces/Propertied.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-entitytype\"></a> `entityType` | `abstract readonly` | `\"project\"` \\| `\"user\"` \\| `\"team\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | How the entity-addressed APIs (favorites) identify this entity's type. | [`FavoritableEntity`](FavoritableEntity.md).[`entityType`](FavoritableEntity.md#property-entitytype) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`FavoritableEntity`](FavoritableEntity.md).[`id`](FavoritableEntity.md#property-id) |\n\n## Methods\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`deleteProperty`](../interfaces/Propertied.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`favorite`](../interfaces/Propertied.md#favorite)\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`favorite`](FavoritableEntity.md#favorite)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`permission`](FavoritableEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`properties`](../interfaces/Propertied.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`setProperty`](../interfaces/Propertied.md#setproperty)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`toJSON`](FavoritableEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`unfavorite`](../interfaces/Propertied.md#unfavorite)\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`unfavorite`](FavoritableEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n\n<!-- src/entities/entity/interfaces/Favoritable.md -->\n# Interface: Favoritable\n\nAn entity that can be added to and removed from the user's favorites.\n\n## Extended by\n\n- [`Propertied`](Propertied.md)\n\n## Methods\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Favoritable`\\>\n\n#### Returns\n\n`Promise`\\<`Favoritable`\\>\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Favoritable`\\>\n\n#### Returns\n\n`Promise`\\<`Favoritable`\\>\n\n\n<!-- src/entities/entity/interfaces/Propertied.md -->\n# Interface: Propertied\n\nA favoritable entity that also carries user-defined properties.\n\n## Extends\n\n- [`Favoritable`](Favoritable.md)\n\n## Methods\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Propertied`\\>\n\n#### Returns\n\n`Promise`\\<`Propertied`\\>\n\n#### Inherited from\n\n[`Favoritable`](Favoritable.md).[`favorite`](Favoritable.md#favorite)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Propertied`\\>\n\n#### Returns\n\n`Promise`\\<`Propertied`\\>\n\n#### Inherited from\n\n[`Favoritable`](Favoritable.md).[`unfavorite`](Favoritable.md#unfavorite)\n\n\n<!-- src/entities/entity/interfaces/PropertyOptionDelta.md -->\n# Interface: PropertyOptionDelta\n\nA delta to apply to one multi-select property.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-add\"></a> `add?` | [`PropertyOption`](../../properties/property-option/classes/PropertyOption.md)[] | Options to add to the property's current selection. |\n| <a id=\"property-property\"></a> `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) | The multi-select property definition to update. |\n| <a id=\"property-remove\"></a> `remove?` | [`PropertyOption`](../../properties/property-option/classes/PropertyOption.md)[] | Options to remove from the property's current selection. |\n\n\n<!-- src/entities/entity/type-aliases/MacroEntityType.md -->\n# Type Alias: MacroEntityType\n\n> **MacroEntityType** = [`FavoriteEntityRef`](../../../../generated/storage/types.gen/type-aliases/FavoriteEntityRef.md)\\[`\"entityType\"`\\]\n\nHow the entity-addressed APIs (favorites) identify an entity's type.\n\n\n<!-- src/entities/messages/thread/classes/MessageThread.md -->\n# Class: MessageThread\n\nA shared message thread with resolution and deletion operations.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-parent\"></a> `parent` | `readonly` | [`MessageParent`](../type-aliases/MessageParent.md) | The entity containing this thread. | - |\n| <a id=\"property-resolved\"></a> `resolved` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the thread is resolved. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(`nonce?`): `Promise`\\<`void`\\>\n\nDelete the entire thread, including replies.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `nonce?` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md); `id`: `string`; `parentId`: `string`; `parentType`: `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"`; \\}\n\nSerialize identity with its owning resource.\n\n#### Returns\n\n\\{ `detail?`: [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md); `id`: `string`; `parentId`: `string`; `parentType`: `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md) |\n| `id` | `string` |\n| `parentId` | `string` |\n| `parentType` | `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` |\n\n#### Overrides\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nResolve the thread or detach its annotation anchor.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `detachAnchor?`: `boolean`; `nonce?`: `string`; `resolved?`: `boolean`; \\} |\n| `options.detachAnchor?` | `boolean` |\n| `options.nonce?` | `string` |\n| `options.resolved?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `parent`, `id`): `MessageThread`\n\nConstruct a scoped thread handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `parent` | [`MessageParent`](../type-aliases/MessageParent.md) |\n| `id` | `string` |\n\n#### Returns\n\n`MessageThread`\n\n\n<!-- src/entities/messages/thread/functions/timeline.md -->\n# Function: timeline()\n\n> **timeline**\\<`TMessage`\\>(`client`, `parent`, `map`, `selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: `TMessage`; `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA bounded mixed message/activity page with typed message handles.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-tmessage\"></a> `TMessage` *extends* [`TimelineMessage`](../type-aliases/TimelineMessage.md) |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `parent` | [`MessageParent`](../type-aliases/MessageParent.md) |\n| `map` | (`record`) => `TMessage` |\n| `selection?` | [`TimelineOptions`](../interfaces/TimelineOptions.md)\\<`TMessage`\\> |\n\n## Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: `TMessage`; `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n\n<!-- src/entities/messages/thread/interfaces/TimelineOptions.md -->\n# Interface: TimelineOptions\\<TMessage\\>\n\nTimeline selection with typed message references and camel case options.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-tmessage\"></a> `TMessage` *extends* [`TimelineMessage`](../type-aliases/TimelineMessage.md) | [`TimelineMessage`](../type-aliases/TimelineMessage.md) |\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-activityafter\"></a> `activityAfter?` | `string` | Inclusive activity lower bound. |\n| <a id=\"property-activitybefore\"></a> `activityBefore?` | `string` | Exclusive activity upper bound. |\n| <a id=\"property-anchored\"></a> `anchored?` | `boolean` | Select anchored threads. |\n| <a id=\"property-around\"></a> `around?` | `TMessage` | Fetch around this message. |\n| <a id=\"property-cursor\"></a> `cursor?` | [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `null` | Opaque continuation cursor from a previous page. |\n| <a id=\"property-direction\"></a> `direction?` | [`MessageDirection`](../../../../../generated/storage/types.gen/type-aliases/MessageDirection.md) | Page direction. |\n| <a id=\"property-includedeletedthreads\"></a> `includeDeletedThreads?` | `boolean` | Include deleted threads. |\n| <a id=\"property-limit\"></a> `limit?` | `number` | Page size. |\n| <a id=\"property-messages\"></a> `messages?` | `TMessage`[] | Restrict selection to these messages. |\n\n\n<!-- src/entities/messages/thread/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `entity`: [`Channel`](../../../channels/channel/classes/Channel.md); `type`: `\"channel\"`; \\} \\| \\{ `entity`: [`Document`](../../../documents/document/classes/Document.md); `type`: `\"document\"`; \\} \\| \\{ `entity`: [`Company`](../../../crm/company/classes/Company.md); `type`: `\"crm_company\"`; \\} \\| \\{ `entity`: [`Contact`](../../../crm/contact/classes/Contact.md); `type`: `\"crm_contact\"`; \\} \\| \\{ `entity`: [`CallRecord`](../../../calls/call-record/classes/CallRecord.md); `type`: `\"call\"`; \\}\n\nThe typed parent of a shared message thread.\n\n\n<!-- src/entities/messages/thread/type-aliases/TimelineMessage.md -->\n# Type Alias: TimelineMessage\n\n> **TimelineMessage** = [`Message`](../../../channels/message/classes/Message.md) \\| [`Comment`](../../../documents/comment/classes/Comment.md) \\| [`CrmComment`](../../../crm/comment/classes/CrmComment.md) \\| [`CallMessage`](../../../calls/message/classes/CallMessage.md)\n\nA message handle accepted by a mixed timeline selector.\n\n\n<!-- src/entities/reference/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity`: [`User`](../../users/user/classes/User.md); `type`: `\"user\"`; \\} \\| \\{ `entity`: [`Team`](../../teams/team/classes/Team.md); `type`: `\"team\"`; \\} \\| \\{ `entity`: [`Document`](../../documents/document/classes/Document.md); `type`: `\"document\"`; \\} \\| \\{ `entity`: [`Chat`](../../chats/chat/classes/Chat.md); `type`: `\"chat\"`; \\} \\| \\{ `entity`: [`Channel`](../../channels/channel/classes/Channel.md); `type`: `\"channel\"`; \\} \\| \\{ `entity`: [`Message`](../../channels/message/classes/Message.md); `type`: `\"channel_message\"`; \\} \\| \\{ `entity`: [`Project`](../../projects/project/classes/Project.md); `type`: `\"project\"`; \\} \\| \\{ `entity`: [`EmailThread`](../../email/thread/classes/EmailThread.md); `type`: `\"email_thread\"`; \\} \\| \\{ `entity`: [`CalendarEvent`](../../calendar/event/classes/CalendarEvent.md); `type`: `\"calendar_event\"`; \\} \\| \\{ `entity`: [`CallRecord`](../../calls/call-record/classes/CallRecord.md); `type`: `\"call\"`; \\} \\| \\{ `entity`: [`ForeignEntity`](../../foreign/foreign-entity/classes/ForeignEntity.md); `type`: `\"foreign_entity\"`; \\} \\| \\{ `entity`: [`Company`](../../crm/company/classes/Company.md); `type`: `\"crm_company\"`; \\} \\| \\{ `entity`: [`Contact`](../../crm/contact/classes/Contact.md); `type`: `\"crm_contact\"`; \\} \\| \\{ `entity`: [`CrmPipeline`](../../crm/pipeline/classes/CrmPipeline.md); `type`: `\"crm_pipeline\"`; \\} \\| \\{ `entity`: [`AgentSession`](../../agent-sessions/agent-session/classes/AgentSession.md); `type`: `\"agent_session\"`; \\} \\| \\{ `entity`: [`Routine`](../../routines/routine/classes/Routine.md); `type`: `\"scheduled_action\"`; \\} \\| \\{ `entity`: [`Initiative`](../../initiatives/initiative/classes/Initiative.md); `type`: `\"initiative\"`; \\} \\| \\{ `entity`: [`Database`](../../databases/database/classes/Database.md); `type`: `\"database\"`; \\} \\| \\{ `entity`: [`DatabaseRow`](../../databases/row/classes/DatabaseRow.md); `type`: `\"database_row\"`; \\} \\| \\{ `entity`: [`Form`](../../forms/form/classes/Form.md); `type`: `\"form\"`; \\}\n\nTyped entity references accepted by cross-resource APIs.\n\n\n<!-- src/entities/search/functions/entitySearch.md -->\n# Function: entitySearch()\n\n> **entitySearch**\\<`T`, `K`\\>(`opts`): (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`T`\\>\n\nBuild a `search(client, query, opts?)` function for one entity type: unified\nsearch hits narrowed to `type`, each mapped through `make`.\nMost relevant first, auto-paginated.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-t\"></a> `T` |\n| <a id=\"type-parameter-k\"></a> `K` *extends* `\"email\"` \\| `\"project\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"company\"` \\| `\"calendarEvent\"` \\| `\"agentSession\"` \\| `\"channelMessage\"` |\n\n## Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `opts` | \\{ `filters?`: [`EntityFilters`](../../../../generated/search/types.gen/type-aliases/EntityFilters.md); `includeCrm?`: `boolean`; `make`: (`client`, `hit`) => `T`; `type`: `K`; \\} | - |\n| `opts.filters?` | [`EntityFilters`](../../../../generated/search/types.gen/type-aliases/EntityFilters.md) | - |\n| `opts.includeCrm?` | `boolean` | Opt in to CRM results (off by default server-side; required for company hits). |\n| `opts.make` | (`client`, `hit`) => `T` | - |\n| `opts.type` | `K` | - |\n\n## Returns\n\n(`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`T`\\>\n\n\n<!-- src/entities/search/interfaces/SearchOpts.md -->\n# Interface: SearchOpts\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-pagesize\"></a> `pageSize?` | `number` |\n| <a id=\"property-searchon\"></a> `searchOn?` | [`SearchOn`](../type-aliases/SearchOn.md) |\n\n\n<!-- src/entities/search/type-aliases/SearchOn.md -->\n# Type Alias: SearchOn\n\n> **SearchOn** = `\"name\"` \\| `\"content\"` \\| `\"name_content\"`\n\n\n<!-- src/entities/sharing/access/classes/AccessRequest.md -->\n# Class: AccessRequest\n\nOne access request; resolutions preserve optimistic concurrency.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](EntityAccess.md) | Entity access surface owning the request. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-requestedlevel\"></a> `requestedLevel` | `readonly` | () => `Promise`\\<[`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)\\> | Requested access. | - |\n| <a id=\"property-requester\"></a> `requester` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | Requesting user. | - |\n| <a id=\"property-revision\"></a> `revision` | `readonly` | () => `Promise`\\<`number`\\> | Request revision. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`RequestStatus`](../../../../../generated/storage/types.gen/type-aliases/RequestStatus.md)\\> | Current request state. | - |\n\n## Methods\n\n### resolve()\n\n> **resolve**(`grantedLevel?`): `Promise`\\<`void`\\>\n\nApprove with an access level, or decline by omitting it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `grantedLevel?` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### from()\n\n> `static` **from**(`client`, `access`, `record`): `AccessRequest`\n\nSeed a request from a state or submission response.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `access` | [`EntityAccess`](EntityAccess.md) |\n| `record` | [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md) |\n\n#### Returns\n\n`AccessRequest`\n\n\n<!-- src/entities/sharing/access/classes/EntityAccess.md -->\n# Class: EntityAccess\n\nAccess requests and direct grants scoped to a shareable entity.\n\n## Constructors\n\n### Constructor\n\n> **new EntityAccess**(`client`, `entityType`, `entity`): `EntityAccess`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `entityType` | [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md) |\n| `entity` | \\{ `id`: `string`; \\} |\n| `entity.id` | `string` |\n\n#### Returns\n\n`EntityAccess`\n\n## Methods\n\n### cancel()\n\n> **cancel**(`revision`): `Promise`\\<`void`\\>\n\nCancel the caller's own request at its observed revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `revision` | `number` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### direct()\n\n> **direct**(): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]\\>\n\nDirect grants expressed as user handles.\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]\\>\n\n***\n\n### grant()\n\n> **grant**(`user`, `accessLevel?`): `Promise`\\<`void`\\>\n\nGrant direct access, or remove it by omitting the access level.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../../users/user/classes/User.md) |\n| `accessLevel?` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### remove()\n\n> **remove**(`user`): `Promise`\\<`void`\\>\n\nRemove one user's direct grant.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../../users/user/classes/User.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### resolve()\n\n> **resolve**(`request`, `resolution`): `Promise`\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\nResolve a request belonging to this entity at an observed revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`AccessRequest`](AccessRequest.md) |\n| `resolution` | [`ResolveRequest`](../../../../../generated/storage/types.gen/type-aliases/ResolveRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\n***\n\n### state()\n\n> **state**(`offset?`): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) \\| `undefined`; `canReview`: `boolean`; `mine`: [`AccessRequest`](AccessRequest.md) \\| `undefined`; `nextOffset`: `number` \\| `undefined`; `owner`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; `pendingCount`: `number`; `requests`: [`AccessRequest`](AccessRequest.md)[]; `supportedLevels`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)[]; \\}\\>\n\nA page of access requests, including the caller's own request and review rights.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `offset?` | `number` |\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) \\| `undefined`; `canReview`: `boolean`; `mine`: [`AccessRequest`](AccessRequest.md) \\| `undefined`; `nextOffset`: `number` \\| `undefined`; `owner`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; `pendingCount`: `number`; `requests`: [`AccessRequest`](AccessRequest.md)[]; `supportedLevels`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)[]; \\}\\>\n\n***\n\n### submit()\n\n> **submit**(`requestedLevel`, `revision?`): `Promise`\\<[`AccessRequest`](AccessRequest.md)\\>\n\nRequest access, optionally naming the revision of an earlier request.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `requestedLevel` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n| `revision?` | `number` |\n\n#### Returns\n\n`Promise`\\<[`AccessRequest`](AccessRequest.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `entity_id`: `string`; `entity_type`: [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md); \\}\n\nSerialize the entity reference without credentials.\n\n#### Returns\n\n\\{ `entity_id`: `string`; `entity_type`: [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md); \\}\n\n| Name | Type |\n| ------ | ------ |\n| `entity_id` | `string` |\n| `entity_type` | [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md) |\n\n\n<!-- src/entities/sharing/permissions/functions/sharePermissionBody.md -->\n# Function: sharePermissionBody()\n\n> **sharePermissionBody**(`options`): [`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md)\n\nConvert sharing options into the generated backend contract.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SharePermissionOptions`](../type-aliases/SharePermissionOptions.md) |\n\n## Returns\n\n[`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md)\n\n\n<!-- src/entities/sharing/permissions/type-aliases/SharePermissionOptions.md -->\n# Type Alias: SharePermissionOptions\n\n> **SharePermissionOptions** = `Omit`\\<[`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md), `\"channelSharePermissions\"`\\> & \\{ `channelSharePermissions?`: \\{ `accessLevel?`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `channel`: [`Channel`](../../../channels/channel/classes/Channel.md); `operation`: [`UpdateChannelSharePermission`](../../../../../generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md)\\[`\"operation\"`\\]; \\}[] \\| `null`; \\}\n\nSharing updates reference channels by handle. Null clears the corresponding grant collection.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `channelSharePermissions?` | \\{ `accessLevel?`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `channel`: [`Channel`](../../../channels/channel/classes/Channel.md); `operation`: [`UpdateChannelSharePermission`](../../../../../generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md)\\[`\"operation\"`\\]; \\}[] \\| `null` | Channel grants to create or replace. |\n\n\n<!-- src/events/receiver/classes/MacroEvents.md -->\n# Class: MacroEvents\n\nPer-instance event receiver. Subscribe with [MacroEvents.on](#on), then\neither [MacroEvents.listen](#listen) (SSE, the default) or mount\n[MacroEvents.webhook](#webhook) at a persisted webhook URL.\n\nObtain via `macro.events` — do not construct directly.\n\n## Constructors\n\n### Constructor\n\n> **new MacroEvents**(`client`, `secret?`): `MacroEvents`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `secret?` | `string` |\n\n#### Returns\n\n`MacroEvents`\n\n## Methods\n\n### handle()\n\n> **handle**(`rawBody`, `headers`): `Promise`\\<`void`\\>\n\nFeed a raw webhook delivery in: verifies the signature, parses, and\ndispatches to matching handlers.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `rawBody` | `string` |\n| `headers` | `DeliveryHeaders` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Throws\n\nif no signing secret was configured, or if the\n signature is missing or invalid.\n\n***\n\n### listen()\n\n> **listen**(`opts?`): `Promise`\\<() => `void`\\>\n\nOpen a live Server-Sent Events stream of matching broker events. This is\nthe default way to receive events — no public URL or signing secret\nrequired. Delivery is best-effort: events published before the\nconnection, while disconnected, or dropped for a slow subscriber are\nmissed; there is no replay.\n\nFilters default to the event names currently registered with [on](#on).\nThe stream uses those filters for its lifetime; later `.on` / unsubscribe\ncalls do not change what the server sends.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`ListenOptions`](../interfaces/ListenOptions.md) |\n\n#### Returns\n\n`Promise`\\<() => `void`\\>\n\nA function that closes the stream.\n\n***\n\n### on()\n\n> **on**\\<`E`\\>(`event`, `handler`): () => `void`\n\nSubscribe to an event across all entities.\n\n#### Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-e\"></a> `E` *extends* `\"agent_session.opened\"` \\| `\"agent_session.turn_started\"` \\| `\"agent_session.turn_ended\"` \\| `\"agent_session.command_rejected\"` \\| `\"agent_session.settled\"` \\| `\"agent_session.waiting_for_input\"` \\| `\"agent_session.input_received\"` \\| `\"agent_session.mentioned\"` \\| `\"agent_session.stopped\"` \\| `\"agent_session.renamed\"` \\| `\"agent_session.deleted\"` \\| `\"channel.picture_changed\"` \\| `\"channel.created\"` \\| `\"channel.updated\"` \\| `\"channel.deleted\"` \\| `\"channel.participant_added\"` \\| `\"channel.participant_removed\"` \\| `\"document.created\"` \\| `\"document.updated\"` \\| `\"document.deleted\"` \\| `\"document.content_uploaded\"` \\| `\"document.sync_content_updated\"` \\| `\"document.purged\"` \\| `\"document.copied\"` \\| `\"document.interaction\"` \\| `\"message.posted\"` \\| `\"message.patched\"` \\| `\"message.deleted\"` \\| `\"message.mentioned\"` \\| `\"message.attachment_created\"` \\| `\"message.attachment_removed\"` |\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `event` | `E` |\n| `handler` | `EventHandler`\\<`E`\\> |\n\n#### Returns\n\nAn unsubscribe function.\n\n() => `void`\n\n***\n\n### onSelfMention()\n\n> **onSelfMention**(`handler`): () => `void`\n\nSubscribe to @-mentions of the authenticated caller: `message.mentioned`\ndeliveries whose mentioned entity is this bot (bot auth) or this user\n(user auth), in channels and in document comments alike.\n\n`message.mentioned` deliveries cover every mention the stream's (or\nwebhook's) workspace can access (its `ids` filter holds channel or\ndocument ids); picking out \"me\" happens here, client-side. The caller's\nidentity is resolved lazily (once) on the first delivery.\n\nFor SSE, register this handler before [listen](#listen) so the derived\nfilters include `message.mentioned`. For persisted webhooks, register the\nwebhook separately, e.g. `macro.webhooks.create({ filters: [{ events:\n['message.mentioned'] }], … })`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `handler` | `EventHandler`\\<`\"message.mentioned\"`\\> |\n\n#### Returns\n\nAn unsubscribe function.\n\n() => `void`\n\n***\n\n### webhook()\n\n> **webhook**(): (`req`) => `Promise`\\<`Response`\\>\n\nA Fetch-style handler to mount at your persisted webhook route.\n\nRequires `webhookSecret` (or `MACRO_WEBHOOK_SECRET`).\n\n#### Returns\n\n(`req`) => `Promise`\\<`Response`\\>\n\n#### Example\n\n```ts\napp.post('/webhook', macro.events.webhook()); // Hono\n```\n\n\n<!-- src/events/receiver/interfaces/ListenOptions.md -->\n# Interface: ListenOptions\n\nOptions for [MacroEvents.listen](../classes/MacroEvents.md#listen).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-filters\"></a> `filters?` | [`WebhookFilter`](../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] | Event/entity-id filters, identical to persisted webhook `filters`. Defaults to one filter covering every event currently registered with [MacroEvents.on](../classes/MacroEvents.md#on). |\n| <a id=\"property-scope\"></a> `scope?` | [`WebhookScope`](../../../../generated/storage/types.gen/type-aliases/WebhookScope.md) | Personal or team workspace whose webhook lifecycle events are delivered. Defaults to `'user'`. |\n| <a id=\"property-signal\"></a> `signal?` | `AbortSignal` | Abort the stream. |\n\n\n<!-- src/macro/classes/Macro.md -->\n# Class: Macro\\<T\\>\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` *extends* [`MacroOpts`](../../config/interfaces/MacroOpts.md) | [`MacroOpts`](../../config/interfaces/MacroOpts.md) |\n\n## Constructors\n\n### Constructor\n\n> **new Macro**\\<`T`\\>(`opts`): `Macro`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | `T` |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-_client\"></a> `_client` | `readonly` | `MacroClient` | Direct access to the underlying hey-api service clients. |\n| <a id=\"property-agents\"></a> `agents` | `readonly` | [`AgentNamespace`](../../entities/agents/namespace/classes/AgentNamespace.md) | agents resources and operations. |\n| <a id=\"property-agentsessions\"></a> `agentSessions` | `readonly` | [`AgentSessionNamespace`](../../entities/agent-sessions/namespace/classes/AgentSessionNamespace.md) | - |\n| <a id=\"property-ai\"></a> `ai` | `readonly` | [`AiNamespace`](../../entities/ai/namespace/classes/AiNamespace.md) | - |\n| <a id=\"property-apikeys\"></a> `apiKeys` | `readonly` | [`ApiKeyNamespace`](../../entities/api-keys/namespace/classes/ApiKeyNamespace.md) | apiKeys resources and operations. |\n| <a id=\"property-bots\"></a> `bots` | `readonly` | [`BotsNamespace`](../../entities/bots/namespace/classes/BotsNamespace.md) | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | [`CalendarNamespace`](../../entities/calendar/namespace/classes/CalendarNamespace.md) | - |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | [`CallRecordNamespace`](../../entities/calls/namespace/classes/CallRecordNamespace.md) | - |\n| <a id=\"property-channels\"></a> `channels` | `readonly` | [`ChannelNamespace`](../../entities/channels/namespace/classes/ChannelNamespace.md) | - |\n| <a id=\"property-chats\"></a> `chats` | `readonly` | [`ChatNamespace`](../../entities/chats/namespace/classes/ChatNamespace.md) | - |\n| <a id=\"property-crm\"></a> `crm` | `readonly` | [`CrmNamespace`](../../entities/crm/namespace/classes/CrmNamespace.md) | - |\n| <a id=\"property-databases\"></a> `databases` | `readonly` | [`DatabaseNamespace`](../../entities/databases/namespace/classes/DatabaseNamespace.md) | - |\n| <a id=\"property-documents\"></a> `documents` | `readonly` | [`DocumentNamespace`](../../entities/documents/namespace/classes/DocumentNamespace.md) | - |\n| <a id=\"property-email\"></a> `email` | `readonly` | [`EmailNamespace`](../../entities/email/namespace/classes/EmailNamespace.md) | - |\n| <a id=\"property-entitymentions\"></a> `entityMentions` | `readonly` | [`EntityMentionNamespace`](../../entities/entity-mentions/namespace/classes/EntityMentionNamespace.md) | entityMentions resources and operations. |\n| <a id=\"property-events\"></a> `events` | `readonly` | [`MacroEvents`](../../events/receiver/classes/MacroEvents.md) | - |\n| <a id=\"property-favorites\"></a> `favorites` | `readonly` | [`FavoritesNamespace`](../../entities/favorites/namespace/classes/FavoritesNamespace.md) | - |\n| <a id=\"property-foreignentities\"></a> `foreignEntities` | `readonly` | [`ForeignEntityNamespace`](../../entities/foreign/namespace/classes/ForeignEntityNamespace.md) | - |\n| <a id=\"property-forms\"></a> `forms` | `readonly` | [`FormNamespace`](../../entities/forms/namespace/classes/FormNamespace.md) | Build forms and submit answers without granting respondents database access. |\n| <a id=\"property-githubpullrequests\"></a> `githubPullRequests` | `readonly` | [`GithubPullRequestNamespace`](../../entities/github-pull-requests/namespace/classes/GithubPullRequestNamespace.md) | githubPullRequests resources and operations. |\n| <a id=\"property-harnesses\"></a> `harnesses` | `readonly` | [`HarnessNamespace`](../../entities/harnesses/namespace/classes/HarnessNamespace.md) | harnesses resources and operations. |\n| <a id=\"property-initiatives\"></a> `initiatives` | `readonly` | [`InitiativeNamespace`](../../entities/initiatives/namespace/classes/InitiativeNamespace.md) | initiatives resources and operations. |\n| <a id=\"property-meetings\"></a> `meetings` | `readonly` | [`MeetingNamespace`](../../entities/meetings/namespace/classes/MeetingNamespace.md) | meetings resources and operations. |\n| <a id=\"property-notifications\"></a> `notifications` | `readonly` | [`NotificationNamespace`](../../entities/notifications/namespace/classes/NotificationNamespace.md) | - |\n| <a id=\"property-pins\"></a> `pins` | `readonly` | [`PinsNamespace`](../../entities/pins/namespace/classes/PinsNamespace.md) | - |\n| <a id=\"property-projects\"></a> `projects` | `readonly` | [`ProjectNamespace`](../../entities/projects/namespace/classes/ProjectNamespace.md) | - |\n| <a id=\"property-properties\"></a> `properties` | `readonly` | [`PropertiesNamespace`](../../entities/properties/namespace/classes/PropertiesNamespace.md) | - |\n| <a id=\"property-routines\"></a> `routines` | `readonly` | [`RoutineNamespace`](../../entities/routines/namespace/classes/RoutineNamespace.md) | routines resources and operations. |\n| <a id=\"property-tasks\"></a> `tasks` | `readonly` | [`TaskNamespace`](../../entities/tasks/namespace/classes/TaskNamespace.md) | - |\n| <a id=\"property-teams\"></a> `teams` | `readonly` | [`TeamNamespace`](../../entities/teams/namespace/classes/TeamNamespace.md) | - |\n| <a id=\"property-unfurls\"></a> `unfurls` | `readonly` | [`UnfurlNamespace`](../../entities/unfurls/namespace/classes/UnfurlNamespace.md) | unfurls resources and operations. |\n| <a id=\"property-users\"></a> `users` | `readonly` | [`UserNamespace`](../../entities/users/namespace/classes/UserNamespace.md) | - |\n| <a id=\"property-webappurl\"></a> `webAppUrl` | `readonly` | `string` | Base URL of the Macro web app, used to build entity URLs. |\n| <a id=\"property-webhooks\"></a> `webhooks` | `readonly` | [`WebhooksNamespace`](../../entities/webhooks/namespace/classes/WebhooksNamespace.md) | - |\n| <a id=\"property-workspace\"></a> `workspace` | `readonly` | [`WorkspaceNamespace`](../../entities/workspace/namespace/classes/WorkspaceNamespace.md) | Browse workspace activity with type, task, time, tag and inbox filters. |\n\n## Methods\n\n### myPrincipalId()\n\n> **myPrincipalId**(): `Promise`\\<`string`\\>\n\nThe authenticated caller's mentionable principal — `bot|<uuid>` for bot\nauth, `macro|<email>` for user auth — fetched once and cached.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### requestedAs()\n\n> **requestedAs**(`user`): `Macro`\\<`T`\\>\n\nClone of this SDK acting on behalf of `user` (sent as\n`x-macro-bot-for-macro-user-id`). Bot auth only — throws for user auth,\nsince a user token always acts as its own user.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../entities/users/user/classes/User.md) |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n\n<!-- src/macro/type-aliases/RequestActivity.md -->\n# Type Alias: RequestActivity\n\n> **RequestActivity** = \\{ `id`: `number`; `operation`: `string`; `service`: `string`; `status`: `\"started\"` \\| `\"completed\"` \\| `\"failed\"`; \\}\n\nA generated SDK operation lifecycle. Contains no arguments, URLs or response data.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-operation\"></a> `operation` | `string` |\n| <a id=\"property-service\"></a> `service` | `string` |\n| <a id=\"property-status\"></a> `status` | `\"started\"` \\| `\"completed\"` \\| `\"failed\"` |\n\n\n<!-- src/mentions/functions/msg.md -->\n# Function: msg()\n\n> **msg**(`strings`, ...`values`): [`RichMessage`](../interfaces/RichMessage.md)\n\nCompose a rich message. Interpolate mentions (a User, Document,\n[here](../variables/here.md), …) or plain strings. Each mention writes its `<m-*>` tag into the\ncontent *and* adds itself to `mentions[]`, so the two can never drift; strings\nare inserted as-is, so markdown like `**bold**` passes through untouched.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `strings` | `TemplateStringsArray` |\n| ...`values` | [`Interpolation`](../type-aliases/Interpolation.md)[] |\n\n## Returns\n\n[`RichMessage`](../interfaces/RichMessage.md)\n\n## Example\n\n```ts\nchannel.send(msg`Hey ${user}, see ${doc}. cc ${here}`);\nchannel.send(msg`Status: ${status} — see ${doc}`);\n```\n\n\n<!-- src/mentions/functions/toBody.md -->\n# Function: toBody()\n\n> **toBody**(`body`): [`RichMessage`](../interfaces/RichMessage.md)\n\nNormalize a plain string or a [RichMessage](../interfaces/RichMessage.md) to the wire shape.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../interfaces/RichMessage.md) |\n\n## Returns\n\n[`RichMessage`](../interfaces/RichMessage.md)\n\n\n<!-- src/mentions/functions/wrapXml.md -->\n# Function: wrapXml()\n\n> **wrapXml**(`tag`, `data`): `string`\n\nSerialize a mention node to its `<tag>{json}</tag>` wire form.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `tag` | `string` |\n| `data` | `unknown` |\n\n## Returns\n\n`string`\n\n\n<!-- src/mentions/interfaces/MentionPart.md -->\n# Interface: MentionPart\n\nThe two things a mentionable entity contributes to a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-mention\"></a> `mention` | [`SimpleMention`](../../../generated/storage/types.gen/type-aliases/SimpleMention.md) | The parallel entry the backend uses for notifications and permissions. |\n| <a id=\"property-tag\"></a> `tag` | `string` | The `<m-*>` tag written into the message content. |\n\n\n<!-- src/mentions/interfaces/Mentionable.md -->\n# Interface: Mentionable\n\nAnything that can be dropped into a [msg](../functions/msg.md) template as a mention.\n\n## Methods\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](MentionPart.md)\n\n\n<!-- src/mentions/interfaces/RichMessage.md -->\n# Interface: RichMessage\n\nA composed message body: content with embedded tags, and the matching mentions.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content\"></a> `content` | `string` |\n| <a id=\"property-mentions\"></a> `mentions` | [`SimpleMention`](../../../generated/storage/types.gen/type-aliases/SimpleMention.md)[] |\n\n\n<!-- src/mentions/type-aliases/Interpolation.md -->\n# Type Alias: Interpolation\n\n> **Interpolation** = [`Mentionable`](../interfaces/Mentionable.md) \\| `string` \\| `number`\n\nWhat may be interpolated into a [msg](../functions/msg.md) template: a mention, or plain text.\n\n\n<!-- src/mentions/variables/here.md -->\n# Variable: here\n\n> `const` **here**: [`Mentionable`](../interfaces/Mentionable.md)\n\nThe `@here` group mention.\n\n\n<!-- src/utils/lazy/classes/Lazy.md -->\n# Class: Lazy\\<T\\>\n\nA value fetched on first access and cached thereafter. Powers thin entity\nhandles: construction is free, the record is loaded lazily the first time a\nfield is read, and concurrent reads share one in-flight request. Pass a\n`seed` when the record is already known (from a list or an event) to skip the\nfetch entirely.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-t\"></a> `T` |\n\n## Constructors\n\n### Constructor\n\n> **new Lazy**\\<`T`\\>(`loader`, `seed?`): `Lazy`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `loader` | () => `Promise`\\<`T`\\> |\n| `seed?` | `T` |\n\n#### Returns\n\n`Lazy`\\<`T`\\>\n\n## Methods\n\n### clear()\n\n> **clear**(): `void`\n\nDrop the cached value so the next read refetches.\n\n#### Returns\n\n`void`\n\n***\n\n### get()\n\n> **get**(): `Promise`\\<`T`\\>\n\n#### Returns\n\n`Promise`\\<`T`\\>\n\n***\n\n### peek()\n\n> **peek**(): `T` \\| `undefined`\n\nThe cached value, if already loaded — never triggers a fetch.\n\n#### Returns\n\n`T` \\| `undefined`\n\n\n<!-- src/utils/pagination/functions/paginate.md -->\n# Function: paginate()\n\n> **paginate**\\<`T`, `Cursor`\\>(`fetchPage`): `AsyncGenerator`\\<`T`\\>\n\nAsync generator over a cursor-paginated API. Iterate with `for await`.\nCursors are plain JSON values (strings or small objects), so a page whose\nnext cursor serialises identically to the one it was fetched with means the\nserver is not advancing; the generator throws instead of looping forever.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` | - |\n| <a id=\"type-parameter-cursor\"></a> `Cursor` | `string` |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `fetchPage` | (`cursor?`) => `Promise`\\<[`Page`](../interfaces/Page.md)\\<`T`, `Cursor`\\>\\> |\n\n## Returns\n\n`AsyncGenerator`\\<`T`\\>\n\n\n<!-- src/utils/pagination/interfaces/Page.md -->\n# Interface: Page\\<T, Cursor\\>\n\nOne page of a cursor-paginated list.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` | - |\n| <a id=\"type-parameter-cursor\"></a> `Cursor` | `string` |\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-items\"></a> `items` | `T`[] |\n| <a id=\"property-nextcursor\"></a> `nextCursor?` | `Cursor` \\| `null` |\n\n\n<!-- src/utils/unwrap/classes/MacroApiError.md -->\n# Class: MacroApiError\n\nA non-2xx HTTP response (Macro API, or a raw fetch like presigned downloads).\n\n## Extends\n\n- [`MacroError`](MacroError.md)\n\n## Extended by\n\n- [`MacroOpRefusedError`](../../../entities/databases/database/classes/MacroOpRefusedError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroApiError**(`status`, `data`): `MacroApiError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `status` | `number` |\n| `data` | `unknown` |\n\n#### Returns\n\n`MacroApiError`\n\n#### Overrides\n\n[`MacroError`](MacroError.md).[`constructor`](MacroError.md#constructor)\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-data\"></a> `data` | `readonly` | `unknown` |\n| <a id=\"property-status\"></a> `status` | `readonly` | `number` |\n\n\n<!-- src/utils/unwrap/classes/MacroError.md -->\n# Class: MacroError\n\nBase for every error the SDK throws.\n\n## Extends\n\n- `Error`\n\n## Extended by\n\n- [`MacroApiError`](MacroApiError.md)\n- [`MacroNotFoundError`](MacroNotFoundError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroError**(`message`): `MacroError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `message` | `string` |\n\n#### Returns\n\n`MacroError`\n\n#### Overrides\n\n`Error.constructor`\n\n\n<!-- src/utils/unwrap/classes/MacroNotFoundError.md -->\n# Class: MacroNotFoundError\n\nThe API succeeded but the addressed entity doesn't exist in the result.\n\n## Extends\n\n- [`MacroError`](MacroError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroNotFoundError**(`message`): `MacroNotFoundError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `message` | `string` |\n\n#### Returns\n\n`MacroNotFoundError`\n\n#### Overrides\n\n[`MacroError`](MacroError.md).[`constructor`](MacroError.md#constructor)\n\n\n<!-- src/utils/unwrap/functions/unwrap.md -->\n# Function: unwrap()\n\n> **unwrap**\\<`TData`, `TError`\\>(`res`): `TData`\n\nTurn a hey-api `{ data, error, response? }` result into either the success\npayload or a thrown MacroApiError.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-tdata\"></a> `TData` |\n| <a id=\"type-parameter-terror\"></a> `TError` |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `res` | \\{ `data?`: `TData`; `error?`: `TError`; `response?`: `Response`; \\} |\n| `res.data?` | `TData` |\n| `res.error?` | `TError` |\n| `res.response?` | `Response` |\n\n## Returns\n\n`TData`\n"
+ "overview": "<!-- src/config/interfaces/MacroOpts.md -->\n# Interface: MacroOpts\n\nOptions passed to `new Macro(opts)` and stored on `MacroClient`.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-auth\"></a> `auth?` | [`MacroAuth`](../type-aliases/MacroAuth.md) | How to authenticate. Takes precedence over `token`. Falls back to `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN` (bot). |\n| <a id=\"property-env\"></a> `env?` | [`Env`](../type-aliases/Env.md) | Which Macro environment to talk to. Falls back to the MACRO_ENV env var, then `'prod'`. |\n| <a id=\"property-hosts\"></a> `hosts?` | `Partial`\\<`Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\> | Override individual service hosts (e.g. point one at localhost). |\n| <a id=\"property-onrequest\"></a> `onRequest?` | (`event`) => `void` | Optional generated API operation events; excludes arguments, URLs and response data. |\n| <a id=\"property-requestedas\"></a> `requestedAs?` | `string` | User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on every request. Bot auth only. Set via `macro.requestedAs(user)` rather than directly. |\n| <a id=\"property-token\"></a> `token?` | [`TokenSource`](../type-aliases/TokenSource.md) | Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API key (`mak_…`) or a bearer token. |\n| <a id=\"property-webappurl\"></a> `webAppUrl?` | `string` | Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. |\n| <a id=\"property-webhooksecret\"></a> `webhookSecret?` | `string` | Signing secret for verifying incoming persisted-webhook deliveries. Required only for `macro.events.webhook()` / `macro.events.handle()`. SSE via `macro.events.listen()` uses the API token and does not need this. Falls back to MACRO_WEBHOOK_SECRET. |\n| <a id=\"property-wsverify\"></a> `wsVerify?` | `string` | - |\n\n\n<!-- src/config/type-aliases/BotScope.md -->\n# Type Alias: BotScope\n\n> **BotScope** = `\"user\"` \\| `\"team\"`\n\nAccess scope for bot-authenticated requests. `user` acts with the\nrequested-as user's access (requires `requestedAs`); `team` acts with the\nbot's owning team's access (team-owned bots only).\n\n\n<!-- src/config/type-aliases/Env.md -->\n# Type Alias: Env\n\n> **Env** = `\"dev\"` \\| `\"prod\"` \\| `\"local\"`\n\n\n<!-- src/config/type-aliases/MacroAuth.md -->\n# Type Alias: MacroAuth\n\n> **MacroAuth** = \\{ `apiKey?`: `never`; `token`: [`TokenSource`](TokenSource.md); `type`: `\"user\"`; \\} \\| \\{ `apiKey`: `string`; `token?`: `never`; `type`: `\"user\"`; \\} \\| \\{ `scope?`: [`BotScope`](BotScope.md); `token`: [`TokenSource`](TokenSource.md); `type`: `\"bot\"`; \\}\n\nHow the SDK authenticates with Macro.\n\nA user has exactly one of two credential fields.\n\n- `token`: a bearer token, or a `mak_` API key. The SDK picks the header\n from the prefix at send time.\n- `apiKey`: a Settings → API Keys key, always sent as\n `x-macro-user-api-key`. Not prefix-checked, so keys that predate the\n `mak_` prefix work here.\n\nA bot uses an `mbot_` token as `x-macro-bot-token` plus\n`x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and\n`team` otherwise.\n\n\n<!-- src/config/type-aliases/ServiceName.md -->\n# Type Alias: ServiceName\n\n> **ServiceName** = `\"agent-harness\"` \\| `\"storage\"` \\| `\"auth\"` \\| `\"email\"` \\| `\"calendar\"` \\| `\"cognition\"` \\| `\"notification\"` \\| `\"properties\"` \\| `\"search\"` \\| `\"scheduled-action\"` \\| `\"static-files\"` \\| `\"connection\"` \\| `\"contacts\"` \\| `\"unfurl\"`\n\nThe backend services the SDK talks to. Note `search` and `properties` are\nserved on the storage host, so they point there.\n\n\n<!-- src/config/type-aliases/TokenSource.md -->\n# Type Alias: TokenSource\n\n> **TokenSource** = `string` \\| (() => `string` \\| `Promise`\\<`string`\\>)\n\nA credential string, or a (possibly async) function that returns one.\n\n\n<!-- src/config/variables/HOSTS.md -->\n# Variable: HOSTS\n\n> `const` **HOSTS**: `Record`\\<[`Env`](../type-aliases/Env.md), `Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\>\n\n\n<!-- src/config/variables/WEB_APP_URLS.md -->\n# Variable: WEB\\_APP\\_URLS\n\n> `const` **WEB\\_APP\\_URLS**: `Record`\\<[`Env`](../type-aliases/Env.md), `string`\\>\n\n\n<!-- src/macro/classes/Macro.md -->\n# Class: Macro\\<T\\>\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` *extends* [`MacroOpts`](../../config/interfaces/MacroOpts.md) | [`MacroOpts`](../../config/interfaces/MacroOpts.md) |\n\n## Constructors\n\n### Constructor\n\n> **new Macro**\\<`T`\\>(`opts`): `Macro`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | `T` |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-_client\"></a> `_client` | `readonly` | `MacroClient` | Direct access to the underlying hey-api service clients. |\n| <a id=\"property-agents\"></a> `agents` | `readonly` | [`AgentNamespace`](../../entities/agents/namespace/classes/AgentNamespace.md) | agents resources and operations. |\n| <a id=\"property-agentsessions\"></a> `agentSessions` | `readonly` | [`AgentSessionNamespace`](../../entities/agent-sessions/namespace/classes/AgentSessionNamespace.md) | - |\n| <a id=\"property-ai\"></a> `ai` | `readonly` | [`AiNamespace`](../../entities/ai/namespace/classes/AiNamespace.md) | - |\n| <a id=\"property-apikeys\"></a> `apiKeys` | `readonly` | [`ApiKeyNamespace`](../../entities/api-keys/namespace/classes/ApiKeyNamespace.md) | apiKeys resources and operations. |\n| <a id=\"property-bots\"></a> `bots` | `readonly` | [`BotsNamespace`](../../entities/bots/namespace/classes/BotsNamespace.md) | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | [`CalendarNamespace`](../../entities/calendar/namespace/classes/CalendarNamespace.md) | - |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | [`CallRecordNamespace`](../../entities/calls/namespace/classes/CallRecordNamespace.md) | - |\n| <a id=\"property-channels\"></a> `channels` | `readonly` | [`ChannelNamespace`](../../entities/channels/namespace/classes/ChannelNamespace.md) | - |\n| <a id=\"property-crm\"></a> `crm` | `readonly` | [`CrmNamespace`](../../entities/crm/namespace/classes/CrmNamespace.md) | - |\n| <a id=\"property-databases\"></a> `databases` | `readonly` | [`DatabaseNamespace`](../../entities/databases/namespace/classes/DatabaseNamespace.md) | - |\n| <a id=\"property-documents\"></a> `documents` | `readonly` | [`DocumentNamespace`](../../entities/documents/namespace/classes/DocumentNamespace.md) | - |\n| <a id=\"property-email\"></a> `email` | `readonly` | [`EmailNamespace`](../../entities/email/namespace/classes/EmailNamespace.md) | - |\n| <a id=\"property-entitymentions\"></a> `entityMentions` | `readonly` | [`EntityMentionNamespace`](../../entities/entity-mentions/namespace/classes/EntityMentionNamespace.md) | entityMentions resources and operations. |\n| <a id=\"property-events\"></a> `events` | `readonly` | [`MacroEvents`](../../events/receiver/classes/MacroEvents.md) | - |\n| <a id=\"property-favorites\"></a> `favorites` | `readonly` | [`FavoritesNamespace`](../../entities/favorites/namespace/classes/FavoritesNamespace.md) | - |\n| <a id=\"property-foreignentities\"></a> `foreignEntities` | `readonly` | [`ForeignEntityNamespace`](../../entities/foreign/namespace/classes/ForeignEntityNamespace.md) | - |\n| <a id=\"property-forms\"></a> `forms` | `readonly` | [`FormNamespace`](../../entities/forms/namespace/classes/FormNamespace.md) | Build forms and submit answers without granting respondents database access. |\n| <a id=\"property-githubpullrequests\"></a> `githubPullRequests` | `readonly` | [`GithubPullRequestNamespace`](../../entities/github-pull-requests/namespace/classes/GithubPullRequestNamespace.md) | githubPullRequests resources and operations. |\n| <a id=\"property-harnesses\"></a> `harnesses` | `readonly` | [`HarnessNamespace`](../../entities/harnesses/namespace/classes/HarnessNamespace.md) | harnesses resources and operations. |\n| <a id=\"property-initiatives\"></a> `initiatives` | `readonly` | [`InitiativeNamespace`](../../entities/initiatives/namespace/classes/InitiativeNamespace.md) | initiatives resources and operations. |\n| <a id=\"property-meetings\"></a> `meetings` | `readonly` | [`MeetingNamespace`](../../entities/meetings/namespace/classes/MeetingNamespace.md) | meetings resources and operations. |\n| <a id=\"property-notifications\"></a> `notifications` | `readonly` | [`NotificationNamespace`](../../entities/notifications/namespace/classes/NotificationNamespace.md) | - |\n| <a id=\"property-pins\"></a> `pins` | `readonly` | [`PinsNamespace`](../../entities/pins/namespace/classes/PinsNamespace.md) | - |\n| <a id=\"property-projects\"></a> `projects` | `readonly` | [`ProjectNamespace`](../../entities/projects/namespace/classes/ProjectNamespace.md) | - |\n| <a id=\"property-properties\"></a> `properties` | `readonly` | [`PropertiesNamespace`](../../entities/properties/namespace/classes/PropertiesNamespace.md) | - |\n| <a id=\"property-routines\"></a> `routines` | `readonly` | [`RoutineNamespace`](../../entities/routines/namespace/classes/RoutineNamespace.md) | routines resources and operations. |\n| <a id=\"property-tasks\"></a> `tasks` | `readonly` | [`TaskNamespace`](../../entities/tasks/namespace/classes/TaskNamespace.md) | - |\n| <a id=\"property-teams\"></a> `teams` | `readonly` | [`TeamNamespace`](../../entities/teams/namespace/classes/TeamNamespace.md) | - |\n| <a id=\"property-unfurls\"></a> `unfurls` | `readonly` | [`UnfurlNamespace`](../../entities/unfurls/namespace/classes/UnfurlNamespace.md) | unfurls resources and operations. |\n| <a id=\"property-users\"></a> `users` | `readonly` | [`UserNamespace`](../../entities/users/namespace/classes/UserNamespace.md) | - |\n| <a id=\"property-webappurl\"></a> `webAppUrl` | `readonly` | `string` | Base URL of the Macro web app, used to build entity URLs. |\n| <a id=\"property-webhooks\"></a> `webhooks` | `readonly` | [`WebhooksNamespace`](../../entities/webhooks/namespace/classes/WebhooksNamespace.md) | - |\n\n## Methods\n\n### myPrincipalId()\n\n> **myPrincipalId**(): `Promise`\\<`string`\\>\n\nThe authenticated caller's mentionable principal — `bot|<uuid>` for bot\nauth, `macro|<email>` for user auth — fetched once and cached.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### requestedAs()\n\n> **requestedAs**(`user`): `Macro`\\<`T`\\>\n\nClone of this SDK acting on behalf of `user` (sent as\n`x-macro-bot-for-macro-user-id`). Bot auth only — throws for user auth,\nsince a user token always acts as its own user.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../entities/users/user/classes/User.md) |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n\n<!-- src/macro/type-aliases/RequestActivity.md -->\n# Type Alias: RequestActivity\n\n> **RequestActivity** = \\{ `id`: `number`; `operation`: `string`; `service`: `string`; `status`: `\"started\"` \\| `\"completed\"` \\| `\"failed\"`; \\}\n\nA generated SDK operation lifecycle. Contains no arguments, URLs or response data.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-operation\"></a> `operation` | `string` |\n| <a id=\"property-service\"></a> `service` | `string` |\n| <a id=\"property-status\"></a> `status` | `\"started\"` \\| `\"completed\"` \\| `\"failed\"` |\n",
+ "documentation": "# Macro SDK: core\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/search/types.gen/type-aliases/AgentSessionFilters.md -->\n# Type Alias: AgentSessionFilters\n\n> **AgentSessionFilters** = \\{ `ids?`: `string`[]; `include?`: `boolean`; `owners?`: `string`[]; \\}\n\nFilters for agent sessions.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] | Agent session ids to filter by. Empty to include all accessible sessions. |\n| <a id=\"property-include\"></a> `include?` | `boolean` | Opt this query into agent sessions at all. Agent sessions are off by default — see [`crate::ast::agent_session::AgentSessionLiteral::Include`]. Asking for specific `ids` or `owners` also opts in. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by session owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Empty to include every owner. |\n\n\n<!-- generated/search/types.gen/type-aliases/CalendarEventFilters.md -->\n# Type Alias: CalendarEventFilters\n\n> **CalendarEventFilters** = \\{ `attendees?`: `string`[]; `calendar_event_ids?`: `string`[]; `ends_after?`: `string` \\| `null`; `organizers?`: `string`[]; `starts_before?`: `string` \\| `null`; `statuses?`: `string`[]; \\}\n\nFilters for canonical calendar-event entities.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | `string`[] | Attendee email addresses. |\n| <a id=\"property-calendar_event_ids\"></a> `calendar_event_ids?` | `string`[] | Canonical event ids. |\n| <a id=\"property-ends_after\"></a> `ends_after?` | `string` \\| `null` | Include master events ending after this instant. |\n| <a id=\"property-organizers\"></a> `organizers?` | `string`[] | Organizer email addresses. |\n| <a id=\"property-starts_before\"></a> `starts_before?` | `string` \\| `null` | Include master events starting before this instant. |\n| <a id=\"property-statuses\"></a> `statuses?` | `string`[] | Event statuses such as `confirmed`, `tentative`, or `cancelled`. |\n\n\n<!-- generated/search/types.gen/type-aliases/CallFilters.md -->\n# Type Alias: CallFilters\n\n> **CallFilters** = \\{ `attended?`: `boolean` \\| `null`; `call_ids?`: `string`[]; `channel_ids?`: `string`[]; `speaker_ids?`: `string`[]; `status?`: `null` \\| [`CallStatus`](CallStatus.md); \\}\n\nFilters for call records.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attended\"></a> `attended?` | `boolean` \\| `null` | Legacy filter by whether the requesting user attended the call. Prefer [`CallFilters::status`] for new callers. `None` = no filter, `Some(true)` = only calls the user joined, `Some(false)` = only calls the user did not join. |\n| <a id=\"property-call_ids\"></a> `call_ids?` | `string`[] | Call record IDs to filter by. Empty to include all calls. |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs to filter calls by. Empty to include all calls. |\n| <a id=\"property-speaker_ids\"></a> `speaker_ids?` | `string`[] | Speaker macro user ids. Empty to include all. |\n| <a id=\"property-status\"></a> `status?` | `null` \\| [`CallStatus`](CallStatus.md) | - |\n\n\n<!-- generated/search/types.gen/type-aliases/CallStatus.md -->\n# Type Alias: CallStatus\n\n> **CallStatus** = `\"ATTENDED\"` \\| `\"MISSED\"` \\| `\"UNATTENDED\"`\n\nViewer-relative attendance status for a call record.\nSerializes as `ATTENDED`, `MISSED`, or `UNATTENDED`.\n\n\n<!-- generated/search/types.gen/type-aliases/ChannelFilters.md -->\n# Type Alias: ChannelFilters\n\n> **ChannelFilters** = \\{ `channel_ids?`: `string`[]; `channel_types?`: `string`[]; `importance?`: `boolean` \\| `null`; `is_participant?`: `boolean` \\| `null`; `mentions?`: `string`[]; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `org_id?`: `number` \\| `null`; `sender_ids?`: `string`[]; `team_id?`: `string` \\| `null`; `thread_ids?`: `string`[]; \\}\n\nThe channel message filters used to filter down what channel messages you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs to search within. Examples: ['general']. Empty to search all accessible channels. |\n| <a id=\"property-channel_types\"></a> `channel_types?` | `string`[] | Channel types to filter by. Examples: ['public'], ['direct_message', 'private']. Empty to search all channel types. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by channel importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-is_participant\"></a> `is_participant?` | `boolean` \\| `null` | Filter by whether the requesting user is an active participant of the channel. Presence of this filter also widens the candidate set to team channels of the user's teams that they have not joined, so `false` matches those channels. None to ignore (participant channels only, today's default). |\n| <a id=\"property-mentions\"></a> `mentions?` | `string`[] | Channel user mentions to search for. Examples: ['@username']. Empty if not filtering by mentions. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by channel notification state. |\n| <a id=\"property-org_id\"></a> `org_id?` | `number` \\| `null` | Channel organization ID to search within. Empty to ignore organization filtering. |\n| <a id=\"property-sender_ids\"></a> `sender_ids?` | `string`[] | Sender IDs to search within. Examples: ['user1']. Empty to search all accessible senders. |\n| <a id=\"property-team_id\"></a> `team_id?` | `string` \\| `null` | Channel team ID to search within. Empty to ignore team filtering. |\n| <a id=\"property-thread_ids\"></a> `thread_ids?` | `string`[] | Channel thread IDs to search within. Examples: ['thread123']. Empty to search all threads. |\n\n\n<!-- generated/search/types.gen/type-aliases/ChannelThreadFilters.md -->\n# Type Alias: ChannelThreadFilters\n\n> **ChannelThreadFilters** = \\{ `channel_ids?`: `string`[]; `participant_ids?`: `string`[]; `root_sender_ids?`: `string`[]; `thread_ids?`: `string`[]; \\}\n\nThe channel thread filters used to filter down channel-thread entities.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channel_ids\"></a> `channel_ids?` | `string`[] | Channel IDs containing the thread. Empty to include threads from all accessible channels. |\n| <a id=\"property-participant_ids\"></a> `participant_ids?` | `string`[] | Thread participant user IDs. A participant is the root message sender, anyone who replied in the thread, or anyone @-mentioned in the thread (group mentions like **Here** count through their per-user expansion at send time). Empty to include threads regardless of participants. |\n| <a id=\"property-root_sender_ids\"></a> `root_sender_ids?` | `string`[] | Sender IDs for the root thread message. Empty to include all root senders. |\n| <a id=\"property-thread_ids\"></a> `thread_ids?` | `string`[] | Channel thread parent message IDs to include. Empty to include all accessible threads. |\n\n\n<!-- generated/search/types.gen/type-aliases/ChatFilters.md -->\n# Type Alias: ChatFilters\n\n> **ChatFilters** = \\{ `chat_ids?`: `string`[]; `importance?`: `boolean` \\| `null`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; `role?`: `string`[]; \\}\n\nThe chat filters used to filter down what chats you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-chat_ids\"></a> `chat_ids?` | `string`[] | Chat ids to search over. Examples: ['chat1'], ['chat1', 'chat2']. When provided, chat search will only match results on these chats. Empty to search all accessible chats. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by chat importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by chat notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by chat owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Examples: ['project1']. Empty to ignore project filtering. |\n| <a id=\"property-role\"></a> `role?` | `string`[] | Chat message roles to search. Examples: ['user'], ['assistant']. Empty to search all roles. |\n\n\n<!-- generated/search/types.gen/type-aliases/CrmCompanyFilters.md -->\n# Type Alias: CrmCompanyFilters\n\n> **CrmCompanyFilters** = \\{ `company_ids?`: `string`[]; `hidden?`: `boolean` \\| `null`; \\}\n\nThe crm company filters used to narrow which CRM companies appear in soup.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-company_ids\"></a> `company_ids?` | `string`[] | CRM company ids to filter by. Examples: ['11111111-...']. Empty to include all of the team's visible CRM companies. |\n| <a id=\"property-hidden\"></a> `hidden?` | `boolean` \\| `null` | Optional `crm_companies.hidden` filter. `None` = visible only (default for back-compat with non-admin callers). `Some(false)` = visible only (explicit). `Some(true)` = hidden only — requires admin/owner team role; enforced by the CRM service from the caller's team receipt. |\n\n\n<!-- generated/search/types.gen/type-aliases/DocumentFilters.md -->\n# Type Alias: DocumentFilters\n\n> **DocumentFilters** = \\{ `document_ids?`: `string`[]; `file_types?`: `string`[]; `importance?`: `boolean` \\| `null`; `is_email_attachment?`: `boolean` \\| `null`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; `sub_types?`: `string`[]; `task_filters?`: [`TaskFilters`](TaskFilters.md); \\}\n\nThe document filters used to filter down what documents you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-document_ids\"></a> `document_ids?` | `string`[] | Document ids to search over. Examples: ['doc1'], ['doc1', 'doc2']. Empty to search all accessible documents. |\n| <a id=\"property-file_types\"></a> `file_types?` | `string`[] | Document file types to search. Examples: ['pdf'], ['md', 'txt']. Empty to search all file types. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by document importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-is_email_attachment\"></a> `is_email_attachment?` | `boolean` \\| `null` | Filter by email attachment status. true = only email attachments, false = only non-email attachments, None = both. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by document notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by document owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Examples: ['project1']. filtering. Empty to ignore project filtering. |\n| <a id=\"property-sub_types\"></a> `sub_types?` | `string`[] | Filter by document sub type. Examples: ['task']. Empty to search all sub types. |\n| <a id=\"property-task_filters\"></a> `task_filters?` | [`TaskFilters`](TaskFilters.md) | Task-specific filters that only apply to task subtype documents. |\n\n\n<!-- generated/search/types.gen/type-aliases/EmailFilters.md -->\n# Type Alias: EmailFilters\n\n> **EmailFilters** = \\{ `bcc?`: `string`[]; `calendar_only?`: `boolean` \\| `null`; `cc?`: `string`[]; `crm_addresses?`: `string`[]; `crm_domains?`: `string`[]; `email_thread_ids?`: `string`[]; `exclude_labels?`: `string`[]; `importance?`: `boolean` \\| `null`; `include_labels?`: `string`[]; `is_read?`: `boolean` \\| `null`; `link_ids?`: `string`[]; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `project_ids?`: `string`[]; `recipients?`: `string`[]; `senders?`: `string`[]; `shared?`: [`SharedEmailFilter`](SharedEmailFilter.md); \\}\n\nThe email filters used to filter down what emails you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-bcc\"></a> `bcc?` | `string`[] | Email BCC addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by BCC. |\n| <a id=\"property-calendar_only\"></a> `calendar_only?` | `boolean` \\| `null` | When `Some(true)`, only include threads that have at least one message with an iCalendar attachment (`.ics` filename or `application/ics` mime type). `Some(false)` and `None` apply no constraint. |\n| <a id=\"property-cc\"></a> `cc?` | `string`[] | Email CC addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by CC. |\n| <a id=\"property-crm_addresses\"></a> `crm_addresses?` | `string`[] | CRM-scoped address filter. When non-empty, expands visibility to every teammate's mailbox and restricts to threads involving any of these fully-qualified addresses. Each address is authorized against `crm_contacts` + `crm_companies` (contact must not be hidden, company must not be hidden, `email_sync` must be true). Mutually exclusive with `crm_domains`. |\n| <a id=\"property-crm_domains\"></a> `crm_domains?` | `string`[] | CRM-scoped domain filter. When non-empty, expands visibility to every teammate's mailbox and restricts to threads involving any of these domains (in any of sender/cc/bcc/recipient). Each domain is authorized against `crm_domains` + `crm_companies` (must exist for the caller's team, company must not be hidden, `email_sync` must be true). Mutually exclusive with `crm_addresses`. |\n| <a id=\"property-email_thread_ids\"></a> `email_thread_ids?` | `string`[] | Email thread IDs to filter by. Examples: ['thread-uuid-1']. Empty to search all threads. |\n| <a id=\"property-exclude_labels\"></a> `exclude_labels?` | `string`[] | Exclude emails that have any of these labels. Supports both Gmail system labels (e.g. \"CATEGORY_PROMOTIONS\") and user-created labels. Empty to not exclude any labels. Note: SPAM and TRASH emails are not indexed in OpenSearch, so they are already excluded by default. |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by email importance. None to not filter. True to show only important emails (drafts, personal, sent, or uncategorized). False to show only unimportant emails (those categorized as promotions, social, updates, or forums). |\n| <a id=\"property-include_labels\"></a> `include_labels?` | `string`[] | Only include emails that have at least one of these labels. Supports both Gmail system labels (e.g. \"INBOX\", \"CATEGORY_PROMOTIONS\") and user-created labels (e.g. \"github\"). Empty to not filter by included labels. Note: SPAM and TRASH emails are not indexed in OpenSearch, so they will never appear in results regardless of this filter. |\n| <a id=\"property-is_read\"></a> `is_read?` | `boolean` \\| `null` | Filter by the email thread's read flag, independently of notification state. |\n| <a id=\"property-link_ids\"></a> `link_ids?` | `string`[] | Restrict to specific inboxes by email_links.id. Empty means \"any inbox the caller can access\" (soup expands to the full set at the router edge). |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by email notification state. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | A list of project ids to search within. Empty to ignore project filtering. |\n| <a id=\"property-recipients\"></a> `recipients?` | `string`[] | Email Recipient addresses to filter by. Examples: ['[email protected]']. Empty if not filtering by Recipient. |\n| <a id=\"property-senders\"></a> `senders?` | `string`[] | Email sender addresses to filter by. Examples: ['[email protected]']. Empty to search all senders. |\n| <a id=\"property-shared\"></a> `shared?` | [`SharedEmailFilter`](SharedEmailFilter.md) | Controls whether shared email threads are included in results. Defaults to \"exclude\" (only the user's own threads). |\n\n\n<!-- generated/search/types.gen/type-aliases/EntityFilters.md -->\n# Type Alias: EntityFilters\n\n> **EntityFilters** = \\{ `agent_session_filters?`: [`AgentSessionFilters`](AgentSessionFilters.md); `calendar_event_filters?`: [`CalendarEventFilters`](CalendarEventFilters.md); `call_filters?`: [`CallFilters`](CallFilters.md); `channel_filters?`: [`ChannelFilters`](ChannelFilters.md); `channel_thread_filters?`: [`ChannelThreadFilters`](ChannelThreadFilters.md); `chat_filters?`: [`ChatFilters`](ChatFilters.md); `crm_company_filters?`: [`CrmCompanyFilters`](CrmCompanyFilters.md); `document_filters?`: [`DocumentFilters`](DocumentFilters.md); `email_filters?`: [`EmailFilters`](EmailFilters.md); `favorites_only?`: `boolean` \\| `null`; `foreign_entity_filters?`: [`ForeignEntityFilters`](ForeignEntityFilters.md); `initiative_filters?`: [`InitiativeFilters`](InitiativeFilters.md); `project_filters?`: [`ProjectFilters`](ProjectFilters.md); `property_filters?`: [`PropertyFilter`](PropertyFilter.md)[]; `tag_filter_mode?`: [`TagFilterMode`](TagFilterMode.md); `tag_option_ids?`: `string`[]; \\}\n\na bundle of all of the filters for each entity type\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-agent_session_filters\"></a> `agent_session_filters?` | [`AgentSessionFilters`](AgentSessionFilters.md) | the bundled [AgentSessionFilters] |\n| <a id=\"property-calendar_event_filters\"></a> `calendar_event_filters?` | [`CalendarEventFilters`](CalendarEventFilters.md) | the bundled [CalendarEventFilters] |\n| <a id=\"property-call_filters\"></a> `call_filters?` | [`CallFilters`](CallFilters.md) | the bundled [CallFilters] |\n| <a id=\"property-channel_filters\"></a> `channel_filters?` | [`ChannelFilters`](ChannelFilters.md) | the bundled [ChannelFilters] |\n| <a id=\"property-channel_thread_filters\"></a> `channel_thread_filters?` | [`ChannelThreadFilters`](ChannelThreadFilters.md) | the bundled [ChannelThreadFilters] |\n| <a id=\"property-chat_filters\"></a> `chat_filters?` | [`ChatFilters`](ChatFilters.md) | the bundled [ChatFilters] |\n| <a id=\"property-crm_company_filters\"></a> `crm_company_filters?` | [`CrmCompanyFilters`](CrmCompanyFilters.md) | the bundled [CrmCompanyFilters] |\n| <a id=\"property-document_filters\"></a> `document_filters?` | [`DocumentFilters`](DocumentFilters.md) | the bundled [DocumentFilters] |\n| <a id=\"property-email_filters\"></a> `email_filters?` | [`EmailFilters`](EmailFilters.md) | the bundled [EmailFilters] |\n| <a id=\"property-favorites_only\"></a> `favorites_only?` | `boolean` \\| `null` | Restrict results to the authenticated viewer's favorites when true. |\n| <a id=\"property-foreign_entity_filters\"></a> `foreign_entity_filters?` | [`ForeignEntityFilters`](ForeignEntityFilters.md) | the bundled [ForeignEntityFilters] |\n| <a id=\"property-initiative_filters\"></a> `initiative_filters?` | [`InitiativeFilters`](InitiativeFilters.md) | Initiative filters. Initiatives are opt-in. |\n| <a id=\"property-project_filters\"></a> `project_filters?` | [`ProjectFilters`](ProjectFilters.md) | the bundled [ProjectFilters] |\n| <a id=\"property-property_filters\"></a> `property_filters?` | [`PropertyFilter`](PropertyFilter.md)[] | property-based filters applied across entity types |\n| <a id=\"property-tag_filter_mode\"></a> `tag_filter_mode?` | [`TagFilterMode`](TagFilterMode.md) | How the `tag_option_ids` combine: `any` (default) matches entities holding at least one selected tag, `all` requires every selected tag. |\n| <a id=\"property-tag_option_ids\"></a> `tag_option_ids?` | `string`[] | tag option ids matched against `properties.values`, OR'd together across all tag definitions. Option ids are globally unique, so the match ignores the owning definition id (personal and team tags combine into one OR). |\n\n\n<!-- generated/search/types.gen/type-aliases/ForeignEntityFilters.md -->\n# Type Alias: ForeignEntityFilters\n\n> **ForeignEntityFilters** = \\{ `foreign_entity_ids?`: `string`[]; `foreign_entity_sources?`: `string`[]; `ids?`: `string`[]; `includes_me?`: `boolean`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); \\}\n\nFilters for foreign entity records.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-foreign_entity_ids\"></a> `foreign_entity_ids?` | `string`[] | External entity identifiers to filter by. Empty to include all external IDs. |\n| <a id=\"property-foreign_entity_sources\"></a> `foreign_entity_sources?` | `string`[] | External source names to filter by. Empty to include all sources. |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] | Internal foreign entity record IDs to filter by. Empty to include all records. |\n| <a id=\"property-includes_me\"></a> `includes_me?` | `boolean` | When true, only return foreign entities whose metadata lists the requesting user as a participant (GitHub `involves:me` semantics for `github_pull_request` records). False or absent applies no filter. Serialized in filter ASTs as the `\"me\"` literal. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by the notification state of the foreign entity (e.g. whether the requesting user's GitHub PR notification is done/seen). |\n\n\n<!-- generated/search/types.gen/type-aliases/InitiativeFilters.md -->\n# Type Alias: InitiativeFilters\n\n> **InitiativeFilters** = \\{ `due_after?`: `string` \\| `null`; `due_before?`: `string` \\| `null`; `include?`: `boolean`; `initiative_ids?`: `string`[]; `name?`: `string` \\| `null`; `owners?`: `string`[]; \\}\n\nFilters for initiatives.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-due_after\"></a> `due_after?` | `string` \\| `null` | Inclusive lower due-date bound. |\n| <a id=\"property-due_before\"></a> `due_before?` | `string` \\| `null` | Inclusive upper due-date bound. |\n| <a id=\"property-include\"></a> `include?` | `boolean` | Opt this query into initiatives at all. Initiatives are off by default — see [`crate::ast::initiative::InitiativeLiteral::Include`]. Asking for specific `initiative_ids` or `owners` also opts in. |\n| <a id=\"property-initiative_ids\"></a> `initiative_ids?` | `string`[] | Initiative ids to filter by. Empty to include all accessible initiatives. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | Case-insensitive name substring. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by initiative owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Empty to include every owner. |\n\n\n<!-- generated/search/types.gen/type-aliases/NotificationFilters.md -->\n# Type Alias: NotificationFilters\n\n> **NotificationFilters** = \\{ `states?`: [`NotificationState`](NotificationState.md)[]; \\}\n\nNotification-level filters that apply to an entity type.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-states\"></a> `states?` | [`NotificationState`](NotificationState.md)[] | Include entities with a non-deleted notification in any of these exact states. Empty means no notification restriction. Active means `[unseen, seen]`. |\n\n\n<!-- generated/search/types.gen/type-aliases/NotificationState.md -->\n# Type Alias: NotificationState\n\n> **NotificationState** = `\"unseen\"` \\| `\"seen\"` \\| `\"done\"`\n\nThe mutually exclusive lifecycle states of a user's notification.\n\n\n<!-- generated/search/types.gen/type-aliases/ProjectFilters.md -->\n# Type Alias: ProjectFilters\n\n> **ProjectFilters** = \\{ `importance?`: `boolean` \\| `null`; `include_root?`: `boolean`; `notification_filters?`: [`NotificationFilters`](NotificationFilters.md); `owners?`: `string`[]; `project_ids?`: `string`[]; \\}\n\nThe project filters used to filter down what projects you search over.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-importance\"></a> `importance?` | `boolean` \\| `null` | Filter by project importance. None to ignore, true to pass through (no clause), false to short-circuit and return nothing. |\n| <a id=\"property-include_root\"></a> `include_root?` | `boolean` | When true, `project_ids` also matches the projects themselves in addition to their children. |\n| <a id=\"property-notification_filters\"></a> `notification_filters?` | [`NotificationFilters`](NotificationFilters.md) | Filter by project notification state. |\n| <a id=\"property-owners\"></a> `owners?` | `string`[] | Filter by project owner principal — a user ('macro\\|[email protected]'), a bot ('bot\\|<uuid>'), or a team (a bare hyphenated uuid). Examples: ['macro\\|[email protected]'], ['macro\\|[email protected]', 'bot\\|0199...']. Empty to search all owners. |\n| <a id=\"property-project_ids\"></a> `project_ids?` | `string`[] | Project IDs to search within. Examples: ['project1']. Empty to search all accessible projects. By default matches children of these projects; set `include_root` to also match the projects themselves. |\n\n\n<!-- generated/search/types.gen/type-aliases/PropertyFilter.md -->\n# Type Alias: PropertyFilter\n\n> **PropertyFilter** = \\{ `entity_ids?`: `string`[]; `entity_type?`: `string` \\| `null`; `option_ids?`: `string`[]; `property_definition_id`: `string`; \\}\n\nA single property-based filter condition.\n\nEach filter targets a specific property definition on entities of a given type,\nmatching against select option UUIDs or entity reference IDs.\nMultiple values within a single filter are OR'd together.\nMultiple filters are AND'd together.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_ids\"></a> `entity_ids?` | `string`[] | Entity reference IDs to match. Multiple values are OR'd together. |\n| <a id=\"property-entity_type\"></a> `entity_type?` | `string` \\| `null` | The entity type for the property lookup (e.g., \"TASK\", \"DOCUMENT\", \"PROJECT\"). When None, matches across all entity types. |\n| <a id=\"property-option_ids\"></a> `option_ids?` | `string`[] | Select option UUIDs to match. Multiple values are OR'd together. |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` | The UUID of the property definition to filter on. |\n\n\n<!-- generated/search/types.gen/type-aliases/SharedEmailFilter.md -->\n# Type Alias: SharedEmailFilter\n\n> **SharedEmailFilter** = `\"exclude\"` \\| `\"include\"` \\| `\"only\"`\n\nControls whether shared email threads are included in results.\n\n\n<!-- generated/search/types.gen/type-aliases/TagFilterMode.md -->\n# Type Alias: TagFilterMode\n\n> **TagFilterMode** = `\"any\"` \\| `\"all\"`\n\nHow multiple `tag_option_ids` combine when filtering.\n\n\n<!-- generated/search/types.gen/type-aliases/TaskFilters.md -->\n# Type Alias: TaskFilters\n\n> **TaskFilters** = \\{ `include_cbm_atm_nc?`: `boolean` \\| `null`; \\}\n\nTask-only filters nested under document filters.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-include_cbm_atm_nc\"></a> `include_cbm_atm_nc?` | `boolean` \\| `null` | Include tasks that are created by me, assigned to me, and not completed, even when they do not match other document filters. |\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessRequest.md -->\n# Type Alias: AccessRequest\n\n> **AccessRequest** = \\{ `createdAt`: `string`; `grantedLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `id`: `string`; `requestedLevel`: [`AccessLevel`](AccessLevel.md); `requesterId`: `string`; `resolvedAt?`: `string` \\| `null`; `retryAfter?`: `string` \\| `null`; `revision`: `number`; `status`: [`RequestStatus`](RequestStatus.md); `updatedAt`: `string`; \\}\n\nLatest request for one person and one entity.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Start of this request attempt. |\n| <a id=\"property-grantedlevel\"></a> `grantedLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-id\"></a> `id` | `string` | Stable request identity across revisions. |\n| <a id=\"property-requestedlevel\"></a> `requestedLevel` | [`AccessLevel`](AccessLevel.md) | Requested upgrade. |\n| <a id=\"property-requesterid\"></a> `requesterId` | `string` | Person requesting access. |\n| <a id=\"property-resolvedat\"></a> `resolvedAt?` | `string` \\| `null` | When the request stopped being pending. |\n| <a id=\"property-retryafter\"></a> `retryAfter?` | `string` \\| `null` | Earliest next submission or level change; cancellation preserves this deadline. Submissions wait one minute, denials wait 24 hours, and approval clears it. |\n| <a id=\"property-revision\"></a> `revision` | `number` | Optimistic concurrency token. |\n| <a id=\"property-status\"></a> `status` | [`RequestStatus`](RequestStatus.md) | Current outcome. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Most recent change. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/FavoriteEntityRef.md -->\n# Type Alias: FavoriteEntityRef\n\n> **FavoriteEntityRef** = \\{ `entityId`: `string`; `entityType`: `\"user\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"project\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"team\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"`; \\}\n\nA reference to a favorited entity.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entityid\"></a> `entityId` | `string` | The id of the favorited entity. |\n| <a id=\"property-entitytype\"></a> `entityType` | `\"user\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"project\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"team\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | The type of the favorited entity. |\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageDirection.md -->\n# Type Alias: MessageDirection\n\n> **MessageDirection** = `\"older\"` \\| `\"newer\"`\n\nDirection through a parent timeline, retaining channel cursor semantics.\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/RequestStatus.md -->\n# Type Alias: RequestStatus\n\n> **RequestStatus** = `\"pending\"` \\| `\"granted\"` \\| `\"denied\"` \\| `\"cancelled\"`\n\nDurable outcome; reading a notification never changes it.\n\n\n<!-- generated/storage/types.gen/type-aliases/ResolveRequest.md -->\n# Type Alias: ResolveRequest\n\n> **ResolveRequest** = \\{ `grantedLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `revision`: `number`; \\}\n\nOwner's decision; omission of a granted level means deny.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-grantedlevel\"></a> `grantedLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-revision\"></a> `revision` | `number` | Request revision being reviewed. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ShareEntityType.md -->\n# Type Alias: ShareEntityType\n\n> **ShareEntityType** = `\"document\"` \\| `\"chat\"` \\| `\"project\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"call\"` \\| `\"email_thread\"` \\| `\"agent_session\"`\n\nAn entity type with an existing Share surface.\n\n\n<!-- generated/storage/types.gen/type-aliases/SimpleMention.md -->\n# Type Alias: SimpleMention\n\n> **SimpleMention** = \\{ `entity_id`: `string`; `entity_type`: `string`; \\}\n\nA mention tracked in a message body.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Mentioned entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Mentioned entity type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadAnchor.md -->\n# Type Alias: ThreadAnchor\n\n> **ThreadAnchor** = \\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\} \\| \\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\} \\| \\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\} \\| \\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\} \\| \\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\nA thread's location within its document. PDF geometry remains annotation-owned.\n\n## Union Members\n\n### Type Literal\n\n\\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `mark_id` | `string` | Mark UUID serialized in the document. |\n| `marked_text?` | `string` \\| `null` | The marked text as it read when the discussion was created, already trimmed and bounded. Absent on threads created or imported before snapshots were captured: the text a mark covers cannot be recovered from the mark id alone. |\n| `type` | `\"markdown\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Highlight annotation UUID. |\n| `marked_text?` | `string` \\| `null` | The text the highlight covers, trimmed and bounded like a markdown snapshot. The highlight owns it and it can be edited there, so it is read from the highlight whenever the thread is, never stored on the thread. Absent when the highlight carries no text. |\n| `type` | `\"pdf_highlight\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Placeable annotation UUID. |\n| `type` | `\"pdf_placeable\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `range` | `string` | A1 cell or range, such as B4 or B4:C9. |\n| `sheetId` | `string` | Stable sheet identity within the workbook. |\n| `sheetName` | `string` | Sheet name when the discussion was created. |\n| `type` | `\"spreadsheet\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `nodeId?` | `string` \\| `null` | Layer the pin follows; absent for a pin on the bare canvas. |\n| `pageId` | `string` | Page (canvas) the pin is on. |\n| `type` | `\"fig\"` | - |\n| `x` | `number` | Horizontal offset from the layer's origin, or the page's when the pin is on no layer, in design units. |\n| `y` | `number` | Vertical offset, measured like `x`. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadState.md -->\n# Type Alias: ThreadState\n\n> **ThreadState** = \\{ `anchor?`: `null` \\| [`ThreadAnchor`](ThreadAnchor.md); `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `resolved`: `boolean`; `root_id`: `string`; `updated_at`: `string`; `user_id`: `string`; \\}\n\nState belonging to a whole thread, keyed by its root message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-anchor\"></a> `anchor?` | `null` \\| [`ThreadAnchor`](ThreadAnchor.md) | - |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time of the discussion. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Explicit deletion of the entire thread, distinct from root deletion. |\n| <a id=\"property-resolved\"></a> `resolved` | `boolean` | Whether this discussion has been resolved. |\n| <a id=\"property-root_id\"></a> `root_id` | `string` | Root message UUID; there is no separate thread identity. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last state change. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User who owns this discussion, including imported discussions. |\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md -->\n# Type Alias: UpdateChannelSharePermission\n\n> **UpdateChannelSharePermission** = \\{ `accessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `channelId`: `string`; `operation`: [`UpdateOperation`](UpdateOperation.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-accesslevel\"></a> `accessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-channelid\"></a> `channelId` | `string` | The channel id |\n| <a id=\"property-operation\"></a> `operation` | [`UpdateOperation`](UpdateOperation.md) | The type of operation to be performed on the chanel share permission You can add, remove or replace and existing permission |\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateOperation.md -->\n# Type Alias: UpdateOperation\n\n> **UpdateOperation** = `\"add\"` \\| `\"remove\"` \\| `\"replace\"`\n\n\n<!-- generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md -->\n# Type Alias: UpdateSharePermissionRequestV2\n\n> **UpdateSharePermissionRequestV2** = \\{ `channelSharePermissions?`: [`UpdateChannelSharePermission`](UpdateChannelSharePermission.md)[] \\| `null`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`UpdateChannelSharePermission`](UpdateChannelSharePermission.md)[] \\| `null` | Any channel share permissions to be created/updated/removed |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookFilter.md -->\n# Type Alias: WebhookFilter\n\n> **WebhookFilter** = \\{ `events`: `string`[]; `ids?`: `string`[] \\| `null`; \\}\n\nEvent and optional entity-id constraints used to match webhook deliveries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-events\"></a> `events` | `string`[] | Event names matched by this filter. |\n| <a id=\"property-ids\"></a> `ids?` | `string`[] \\| `null` | Entity ids matched by this filter. When absent, the filter matches all entity ids. |\n\n\n<!-- generated/storage/types.gen/type-aliases/WebhookScope.md -->\n# Type Alias: WebhookScope\n\n> **WebhookScope** = `\"user\"` \\| `\"team\"`\n\nScope that owns a newly-created webhook.\n\nClients serialize this, so both derives are used. `Display`/`FromStr`\nspell the same names as serde, for query strings and config values.\n\n\n<!-- src/config/interfaces/MacroOpts.md -->\n# Interface: MacroOpts\n\nOptions passed to `new Macro(opts)` and stored on `MacroClient`.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-auth\"></a> `auth?` | [`MacroAuth`](../type-aliases/MacroAuth.md) | How to authenticate. Takes precedence over `token`. Falls back to `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN` (bot). |\n| <a id=\"property-env\"></a> `env?` | [`Env`](../type-aliases/Env.md) | Which Macro environment to talk to. Falls back to the MACRO_ENV env var, then `'prod'`. |\n| <a id=\"property-hosts\"></a> `hosts?` | `Partial`\\<`Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\> | Override individual service hosts (e.g. point one at localhost). |\n| <a id=\"property-onrequest\"></a> `onRequest?` | (`event`) => `void` | Optional generated API operation events; excludes arguments, URLs and response data. |\n| <a id=\"property-requestedas\"></a> `requestedAs?` | `string` | User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on every request. Bot auth only. Set via `macro.requestedAs(user)` rather than directly. |\n| <a id=\"property-token\"></a> `token?` | [`TokenSource`](../type-aliases/TokenSource.md) | Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API key (`mak_…`) or a bearer token. |\n| <a id=\"property-webappurl\"></a> `webAppUrl?` | `string` | Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. |\n| <a id=\"property-webhooksecret\"></a> `webhookSecret?` | `string` | Signing secret for verifying incoming persisted-webhook deliveries. Required only for `macro.events.webhook()` / `macro.events.handle()`. SSE via `macro.events.listen()` uses the API token and does not need this. Falls back to MACRO_WEBHOOK_SECRET. |\n| <a id=\"property-wsverify\"></a> `wsVerify?` | `string` | - |\n\n\n<!-- src/config/type-aliases/BotScope.md -->\n# Type Alias: BotScope\n\n> **BotScope** = `\"user\"` \\| `\"team\"`\n\nAccess scope for bot-authenticated requests. `user` acts with the\nrequested-as user's access (requires `requestedAs`); `team` acts with the\nbot's owning team's access (team-owned bots only).\n\n\n<!-- src/config/type-aliases/Env.md -->\n# Type Alias: Env\n\n> **Env** = `\"dev\"` \\| `\"prod\"` \\| `\"local\"`\n\n\n<!-- src/config/type-aliases/MacroAuth.md -->\n# Type Alias: MacroAuth\n\n> **MacroAuth** = \\{ `apiKey?`: `never`; `token`: [`TokenSource`](TokenSource.md); `type`: `\"user\"`; \\} \\| \\{ `apiKey`: `string`; `token?`: `never`; `type`: `\"user\"`; \\} \\| \\{ `scope?`: [`BotScope`](BotScope.md); `token`: [`TokenSource`](TokenSource.md); `type`: `\"bot\"`; \\}\n\nHow the SDK authenticates with Macro.\n\nA user has exactly one of two credential fields.\n\n- `token`: a bearer token, or a `mak_` API key. The SDK picks the header\n from the prefix at send time.\n- `apiKey`: a Settings → API Keys key, always sent as\n `x-macro-user-api-key`. Not prefix-checked, so keys that predate the\n `mak_` prefix work here.\n\nA bot uses an `mbot_` token as `x-macro-bot-token` plus\n`x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and\n`team` otherwise.\n\n\n<!-- src/config/type-aliases/ServiceName.md -->\n# Type Alias: ServiceName\n\n> **ServiceName** = `\"agent-harness\"` \\| `\"storage\"` \\| `\"auth\"` \\| `\"email\"` \\| `\"calendar\"` \\| `\"cognition\"` \\| `\"notification\"` \\| `\"properties\"` \\| `\"search\"` \\| `\"scheduled-action\"` \\| `\"static-files\"` \\| `\"connection\"` \\| `\"contacts\"` \\| `\"unfurl\"`\n\nThe backend services the SDK talks to. Note `search` and `properties` are\nserved on the storage host, so they point there.\n\n\n<!-- src/config/type-aliases/TokenSource.md -->\n# Type Alias: TokenSource\n\n> **TokenSource** = `string` \\| (() => `string` \\| `Promise`\\<`string`\\>)\n\nA credential string, or a (possibly async) function that returns one.\n\n\n<!-- src/config/variables/HOSTS.md -->\n# Variable: HOSTS\n\n> `const` **HOSTS**: `Record`\\<[`Env`](../type-aliases/Env.md), `Record`\\<[`ServiceName`](../type-aliases/ServiceName.md), `string`\\>\\>\n\n\n<!-- src/config/variables/WEB_APP_URLS.md -->\n# Variable: WEB\\_APP\\_URLS\n\n> `const` **WEB\\_APP\\_URLS**: `Record`\\<[`Env`](../type-aliases/Env.md), `string`\\>\n\n\n<!-- src/entities/entity/classes/FavoritableEntity.md -->\n# Abstract Class: FavoritableEntity\\<Detail\\>\n\nAn entity the favorites API can address, and so can be (un)favorited.\n\n## Extends\n\n- [`MacroEntity`](MacroEntity.md)\\<`Detail`\\>\n\n## Extended by\n\n- [`CallRecord`](../../calls/call-record/classes/CallRecord.md)\n- [`Message`](../../channels/message/classes/Message.md)\n- [`Contact`](../../crm/contact/classes/Contact.md)\n- [`PropertiedEntity`](PropertiedEntity.md)\n- [`ForeignEntity`](../../foreign/foreign-entity/classes/ForeignEntity.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Implements\n\n- [`Favoritable`](../interfaces/Favoritable.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-entitytype\"></a> `entityType` | `abstract readonly` | `\"project\"` \\| `\"user\"` \\| `\"team\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | How the entity-addressed APIs (favorites) identify this entity's type. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](MacroEntity.md).[`id`](MacroEntity.md#property-id) |\n\n## Methods\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Favoritable`](../interfaces/Favoritable.md).[`favorite`](../interfaces/Favoritable.md#favorite)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](MacroEntity.md).[`toJSON`](MacroEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`FavoritableEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Favoritable`](../interfaces/Favoritable.md).[`unfavorite`](../interfaces/Favoritable.md#unfavorite)\n\n\n<!-- src/entities/entity/classes/MacroEntity.md -->\n# Abstract Class: MacroEntity\\<Detail\\>\n\nBase for entity handles: a free-to-construct `(client, id)` pair whose\ndetail record loads lazily on first field access and is dropped after any\nmutation. Subclasses implement fetch and build their surface from\nfield and mutate.\n\n## Extended by\n\n- [`AgentSession`](../../agent-sessions/agent-session/classes/AgentSession.md)\n- [`CodeExecution`](../../agent-sessions/code-execution/classes/CodeExecution.md)\n- [`SessionReview`](../../agent-sessions/review/classes/SessionReview.md)\n- [`Agent`](../../agents/agent/classes/Agent.md)\n- [`UserApiKey`](../../api-keys/api-key/classes/UserApiKey.md)\n- [`Calendar`](../../calendar/calendar/classes/Calendar.md)\n- [`CalendarEvent`](../../calendar/event/classes/CalendarEvent.md)\n- [`CallMessage`](../../calls/message/classes/CallMessage.md)\n- [`ChatMessage`](../../chats/generation/classes/ChatMessage.md)\n- [`CrmComment`](../../crm/comment/classes/CrmComment.md)\n- [`CrmPipeline`](../../crm/pipeline/classes/CrmPipeline.md)\n- [`PipelineTable`](../../crm/pipeline/classes/PipelineTable.md)\n- [`PipelineRow`](../../crm/pipeline/classes/PipelineRow.md)\n- [`PipelineColumn`](../../crm/pipeline/classes/PipelineColumn.md)\n- [`Database`](../../databases/database/classes/Database.md)\n- [`DocumentAnchor`](../../documents/anchor/classes/DocumentAnchor.md)\n- [`Comment`](../../documents/comment/classes/Comment.md)\n- [`EmailAttachment`](../../email/attachment/classes/EmailAttachment.md)\n- [`EmailFilter`](../../email/filter/classes/EmailFilter.md)\n- [`Label`](../../email/label/classes/Label.md)\n- [`Link`](../../email/link/classes/Link.md)\n- [`EmailMessage`](../../email/message/classes/EmailMessage.md)\n- [`FavoritableEntity`](FavoritableEntity.md)\n- [`Form`](../../forms/form/classes/Form.md)\n- [`GithubPullRequest`](../../github-pull-requests/pull-request/classes/GithubPullRequest.md)\n- [`Harness`](../../harnesses/harness/classes/Harness.md)\n- [`HarnessPairing`](../../harnesses/pairing/classes/HarnessPairing.md)\n- [`Initiative`](../../initiatives/initiative/classes/Initiative.md)\n- [`Meeting`](../../meetings/meeting/classes/Meeting.md)\n- [`MessageThread`](../../messages/thread/classes/MessageThread.md)\n- [`Notification`](../../notifications/notification/classes/Notification.md)\n- [`Routine`](../../routines/routine/classes/Routine.md)\n- [`AccessRequest`](../../sharing/access/classes/AccessRequest.md)\n- [`Team`](../../teams/team/classes/Team.md)\n- [`Webhook`](../../webhooks/webhook/classes/Webhook.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` |\n\n## Methods\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n\n<!-- src/entities/entity/classes/PropertiedEntity.md -->\n# Abstract Class: PropertiedEntity\\<Detail\\>\n\nA favoritable entity that also carries user-defined properties.\n\n## Extends\n\n- [`FavoritableEntity`](FavoritableEntity.md)\\<`Detail`\\>\n\n## Extended by\n\n- [`Channel`](../../channels/channel/classes/Channel.md)\n- [`Chat`](../../chats/chat/classes/Chat.md)\n- [`Company`](../../crm/company/classes/Company.md)\n- [`Document`](../../documents/document/classes/Document.md)\n- [`EmailThread`](../../email/thread/classes/EmailThread.md)\n- [`Project`](../../projects/project/classes/Project.md)\n- [`User`](../../users/user/classes/User.md)\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-detail\"></a> `Detail` |\n\n## Implements\n\n- [`Propertied`](../interfaces/Propertied.md)\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-entitytype\"></a> `entityType` | `abstract readonly` | `\"project\"` \\| `\"user\"` \\| `\"team\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"channel_message\"` \\| `\"document\"` \\| `\"email_thread\"` \\| `\"calendar_event\"` \\| `\"call\"` \\| `\"foreign_entity\"` \\| `\"static_file\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` \\| `\"crm_pipeline\"` \\| `\"reminder\"` \\| `\"skill\"` \\| `\"agent_session\"` \\| `\"scheduled_action\"` \\| `\"initiative\"` \\| `\"database\"` \\| `\"database_row\"` \\| `\"form\"` | How the entity-addressed APIs (favorites) identify this entity's type. | [`FavoritableEntity`](FavoritableEntity.md).[`entityType`](FavoritableEntity.md#property-entitytype) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`FavoritableEntity`](FavoritableEntity.md).[`id`](FavoritableEntity.md#property-id) |\n\n## Methods\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`deleteProperty`](../interfaces/Propertied.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`favorite`](../interfaces/Propertied.md#favorite)\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`favorite`](FavoritableEntity.md#favorite)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`permission`](FavoritableEntity.md#permission)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`properties`](../interfaces/Propertied.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`setProperty`](../interfaces/Propertied.md#setproperty)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: `Detail`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | `Detail` |\n| `id` | `string` |\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`toJSON`](FavoritableEntity.md#tojson)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`PropertiedEntity`\\<`Detail`\\>\\>\n\n#### Implementation of\n\n[`Propertied`](../interfaces/Propertied.md).[`unfavorite`](../interfaces/Propertied.md#unfavorite)\n\n#### Inherited from\n\n[`FavoritableEntity`](FavoritableEntity.md).[`unfavorite`](FavoritableEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n\n<!-- src/entities/entity/interfaces/Favoritable.md -->\n# Interface: Favoritable\n\nAn entity that can be added to and removed from the user's favorites.\n\n## Extended by\n\n- [`Propertied`](Propertied.md)\n\n## Methods\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Favoritable`\\>\n\n#### Returns\n\n`Promise`\\<`Favoritable`\\>\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Favoritable`\\>\n\n#### Returns\n\n`Promise`\\<`Favoritable`\\>\n\n\n<!-- src/entities/entity/interfaces/Propertied.md -->\n# Interface: Propertied\n\nA favoritable entity that also carries user-defined properties.\n\n## Extends\n\n- [`Favoritable`](Favoritable.md)\n\n## Methods\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Propertied`\\>\n\n#### Returns\n\n`Promise`\\<`Propertied`\\>\n\n#### Inherited from\n\n[`Favoritable`](Favoritable.md).[`favorite`](Favoritable.md#favorite)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Propertied`\\>\n\n#### Returns\n\n`Promise`\\<`Propertied`\\>\n\n#### Inherited from\n\n[`Favoritable`](Favoritable.md).[`unfavorite`](Favoritable.md#unfavorite)\n\n\n<!-- src/entities/entity/interfaces/PropertyOptionDelta.md -->\n# Interface: PropertyOptionDelta\n\nA delta to apply to one multi-select property.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-add\"></a> `add?` | [`PropertyOption`](../../properties/property-option/classes/PropertyOption.md)[] | Options to add to the property's current selection. |\n| <a id=\"property-property\"></a> `property` | [`PropertyDefinition`](../../properties/property-definition/classes/PropertyDefinition.md) | The multi-select property definition to update. |\n| <a id=\"property-remove\"></a> `remove?` | [`PropertyOption`](../../properties/property-option/classes/PropertyOption.md)[] | Options to remove from the property's current selection. |\n\n\n<!-- src/entities/entity/type-aliases/MacroEntityType.md -->\n# Type Alias: MacroEntityType\n\n> **MacroEntityType** = [`FavoriteEntityRef`](../../../../generated/storage/types.gen/type-aliases/FavoriteEntityRef.md)\\[`\"entityType\"`\\]\n\nHow the entity-addressed APIs (favorites) identify an entity's type.\n\n\n<!-- src/entities/messages/thread/classes/MessageThread.md -->\n# Class: MessageThread\n\nA shared message thread with resolution and deletion operations.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-parent\"></a> `parent` | `readonly` | [`MessageParent`](../type-aliases/MessageParent.md) | The entity containing this thread. | - |\n| <a id=\"property-resolved\"></a> `resolved` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the thread is resolved. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(`nonce?`): `Promise`\\<`void`\\>\n\nDelete the entire thread, including replies.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `nonce?` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md); `id`: `string`; `parentId`: `string`; `parentType`: `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"`; \\}\n\nSerialize identity with its owning resource.\n\n#### Returns\n\n\\{ `detail?`: [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md); `id`: `string`; `parentId`: `string`; `parentType`: `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md) |\n| `id` | `string` |\n| `parentId` | `string` |\n| `parentType` | `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"crm_company\"` \\| `\"crm_contact\"` |\n\n#### Overrides\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`void`\\>\n\nResolve the thread or detach its annotation anchor.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `detachAnchor?`: `boolean`; `nonce?`: `string`; `resolved?`: `boolean`; \\} |\n| `options.detachAnchor?` | `boolean` |\n| `options.nonce?` | `string` |\n| `options.resolved?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `parent`, `id`): `MessageThread`\n\nConstruct a scoped thread handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `parent` | [`MessageParent`](../type-aliases/MessageParent.md) |\n| `id` | `string` |\n\n#### Returns\n\n`MessageThread`\n\n\n<!-- src/entities/messages/thread/functions/timeline.md -->\n# Function: timeline()\n\n> **timeline**\\<`TMessage`\\>(`client`, `parent`, `map`, `selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: `TMessage`; `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA bounded mixed message/activity page with typed message handles.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-tmessage\"></a> `TMessage` *extends* [`TimelineMessage`](../type-aliases/TimelineMessage.md) |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `parent` | [`MessageParent`](../type-aliases/MessageParent.md) |\n| `map` | (`record`) => `TMessage` |\n| `selection?` | [`TimelineOptions`](../interfaces/TimelineOptions.md)\\<`TMessage`\\> |\n\n## Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: `TMessage`; `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n\n<!-- src/entities/messages/thread/interfaces/TimelineOptions.md -->\n# Interface: TimelineOptions\\<TMessage\\>\n\nTimeline selection with typed message references and camel case options.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-tmessage\"></a> `TMessage` *extends* [`TimelineMessage`](../type-aliases/TimelineMessage.md) | [`TimelineMessage`](../type-aliases/TimelineMessage.md) |\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-activityafter\"></a> `activityAfter?` | `string` | Inclusive activity lower bound. |\n| <a id=\"property-activitybefore\"></a> `activityBefore?` | `string` | Exclusive activity upper bound. |\n| <a id=\"property-anchored\"></a> `anchored?` | `boolean` | Select anchored threads. |\n| <a id=\"property-around\"></a> `around?` | `TMessage` | Fetch around this message. |\n| <a id=\"property-cursor\"></a> `cursor?` | [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `null` | Opaque continuation cursor from a previous page. |\n| <a id=\"property-direction\"></a> `direction?` | [`MessageDirection`](../../../../../generated/storage/types.gen/type-aliases/MessageDirection.md) | Page direction. |\n| <a id=\"property-includedeletedthreads\"></a> `includeDeletedThreads?` | `boolean` | Include deleted threads. |\n| <a id=\"property-limit\"></a> `limit?` | `number` | Page size. |\n| <a id=\"property-messages\"></a> `messages?` | `TMessage`[] | Restrict selection to these messages. |\n\n\n<!-- src/entities/messages/thread/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `entity`: [`Channel`](../../../channels/channel/classes/Channel.md); `type`: `\"channel\"`; \\} \\| \\{ `entity`: [`Document`](../../../documents/document/classes/Document.md); `type`: `\"document\"`; \\} \\| \\{ `entity`: [`Company`](../../../crm/company/classes/Company.md); `type`: `\"crm_company\"`; \\} \\| \\{ `entity`: [`Contact`](../../../crm/contact/classes/Contact.md); `type`: `\"crm_contact\"`; \\} \\| \\{ `entity`: [`CallRecord`](../../../calls/call-record/classes/CallRecord.md); `type`: `\"call\"`; \\}\n\nThe typed parent of a shared message thread.\n\n\n<!-- src/entities/messages/thread/type-aliases/TimelineMessage.md -->\n# Type Alias: TimelineMessage\n\n> **TimelineMessage** = [`Message`](../../../channels/message/classes/Message.md) \\| [`Comment`](../../../documents/comment/classes/Comment.md) \\| [`CrmComment`](../../../crm/comment/classes/CrmComment.md) \\| [`CallMessage`](../../../calls/message/classes/CallMessage.md)\n\nA message handle accepted by a mixed timeline selector.\n\n\n<!-- src/entities/reference/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity`: [`User`](../../users/user/classes/User.md); `type`: `\"user\"`; \\} \\| \\{ `entity`: [`Team`](../../teams/team/classes/Team.md); `type`: `\"team\"`; \\} \\| \\{ `entity`: [`Document`](../../documents/document/classes/Document.md); `type`: `\"document\"`; \\} \\| \\{ `entity`: [`Chat`](../../chats/chat/classes/Chat.md); `type`: `\"chat\"`; \\} \\| \\{ `entity`: [`Channel`](../../channels/channel/classes/Channel.md); `type`: `\"channel\"`; \\} \\| \\{ `entity`: [`Message`](../../channels/message/classes/Message.md); `type`: `\"channel_message\"`; \\} \\| \\{ `entity`: [`Project`](../../projects/project/classes/Project.md); `type`: `\"project\"`; \\} \\| \\{ `entity`: [`EmailThread`](../../email/thread/classes/EmailThread.md); `type`: `\"email_thread\"`; \\} \\| \\{ `entity`: [`CalendarEvent`](../../calendar/event/classes/CalendarEvent.md); `type`: `\"calendar_event\"`; \\} \\| \\{ `entity`: [`CallRecord`](../../calls/call-record/classes/CallRecord.md); `type`: `\"call\"`; \\} \\| \\{ `entity`: [`ForeignEntity`](../../foreign/foreign-entity/classes/ForeignEntity.md); `type`: `\"foreign_entity\"`; \\} \\| \\{ `entity`: [`Company`](../../crm/company/classes/Company.md); `type`: `\"crm_company\"`; \\} \\| \\{ `entity`: [`Contact`](../../crm/contact/classes/Contact.md); `type`: `\"crm_contact\"`; \\} \\| \\{ `entity`: [`CrmPipeline`](../../crm/pipeline/classes/CrmPipeline.md); `type`: `\"crm_pipeline\"`; \\} \\| \\{ `entity`: [`AgentSession`](../../agent-sessions/agent-session/classes/AgentSession.md); `type`: `\"agent_session\"`; \\} \\| \\{ `entity`: [`Routine`](../../routines/routine/classes/Routine.md); `type`: `\"scheduled_action\"`; \\} \\| \\{ `entity`: [`Initiative`](../../initiatives/initiative/classes/Initiative.md); `type`: `\"initiative\"`; \\} \\| \\{ `entity`: [`Database`](../../databases/database/classes/Database.md); `type`: `\"database\"`; \\} \\| \\{ `entity`: [`DatabaseRow`](../../databases/row/classes/DatabaseRow.md); `type`: `\"database_row\"`; \\} \\| \\{ `entity`: [`Form`](../../forms/form/classes/Form.md); `type`: `\"form\"`; \\}\n\nTyped entity references accepted by cross-resource APIs.\n\n\n<!-- src/entities/search/functions/entitySearch.md -->\n# Function: entitySearch()\n\n> **entitySearch**\\<`T`, `K`\\>(`opts`): (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`T`\\>\n\nBuild a `search(client, query, opts?)` function for one entity type: unified\nsearch hits narrowed to `type`, each mapped through `make`.\nMost relevant first, auto-paginated.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-t\"></a> `T` |\n| <a id=\"type-parameter-k\"></a> `K` *extends* `\"email\"` \\| `\"project\"` \\| `\"chat\"` \\| `\"channel\"` \\| `\"document\"` \\| `\"call\"` \\| `\"company\"` \\| `\"calendarEvent\"` \\| `\"agentSession\"` \\| `\"channelMessage\"` |\n\n## Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `opts` | \\{ `filters?`: [`EntityFilters`](../../../../generated/search/types.gen/type-aliases/EntityFilters.md); `includeCrm?`: `boolean`; `make`: (`client`, `hit`) => `T`; `type`: `K`; \\} | - |\n| `opts.filters?` | [`EntityFilters`](../../../../generated/search/types.gen/type-aliases/EntityFilters.md) | - |\n| `opts.includeCrm?` | `boolean` | Opt in to CRM results (off by default server-side; required for company hits). |\n| `opts.make` | (`client`, `hit`) => `T` | - |\n| `opts.type` | `K` | - |\n\n## Returns\n\n(`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`T`\\>\n\n\n<!-- src/entities/search/interfaces/SearchOpts.md -->\n# Interface: SearchOpts\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-pagesize\"></a> `pageSize?` | `number` |\n| <a id=\"property-searchon\"></a> `searchOn?` | [`SearchOn`](../type-aliases/SearchOn.md) |\n\n\n<!-- src/entities/search/type-aliases/SearchOn.md -->\n# Type Alias: SearchOn\n\n> **SearchOn** = `\"name\"` \\| `\"content\"` \\| `\"name_content\"`\n\n\n<!-- src/entities/sharing/access/classes/AccessRequest.md -->\n# Class: AccessRequest\n\nOne access request; resolutions preserve optimistic concurrency.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](EntityAccess.md) | Entity access surface owning the request. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-requestedlevel\"></a> `requestedLevel` | `readonly` | () => `Promise`\\<[`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)\\> | Requested access. | - |\n| <a id=\"property-requester\"></a> `requester` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | Requesting user. | - |\n| <a id=\"property-revision\"></a> `revision` | `readonly` | () => `Promise`\\<`number`\\> | Request revision. | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`RequestStatus`](../../../../../generated/storage/types.gen/type-aliases/RequestStatus.md)\\> | Current request state. | - |\n\n## Methods\n\n### resolve()\n\n> **resolve**(`grantedLevel?`): `Promise`\\<`void`\\>\n\nApprove with an access level, or decline by omitting it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `grantedLevel?` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### from()\n\n> `static` **from**(`client`, `access`, `record`): `AccessRequest`\n\nSeed a request from a state or submission response.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `access` | [`EntityAccess`](EntityAccess.md) |\n| `record` | [`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md) |\n\n#### Returns\n\n`AccessRequest`\n\n\n<!-- src/entities/sharing/access/classes/EntityAccess.md -->\n# Class: EntityAccess\n\nAccess requests and direct grants scoped to a shareable entity.\n\n## Constructors\n\n### Constructor\n\n> **new EntityAccess**(`client`, `entityType`, `entity`): `EntityAccess`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `entityType` | [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md) |\n| `entity` | \\{ `id`: `string`; \\} |\n| `entity.id` | `string` |\n\n#### Returns\n\n`EntityAccess`\n\n## Methods\n\n### cancel()\n\n> **cancel**(`revision`): `Promise`\\<`void`\\>\n\nCancel the caller's own request at its observed revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `revision` | `number` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### direct()\n\n> **direct**(): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]\\>\n\nDirect grants expressed as user handles.\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]\\>\n\n***\n\n### grant()\n\n> **grant**(`user`, `accessLevel?`): `Promise`\\<`void`\\>\n\nGrant direct access, or remove it by omitting the access level.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../../users/user/classes/User.md) |\n| `accessLevel?` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### remove()\n\n> **remove**(`user`): `Promise`\\<`void`\\>\n\nRemove one user's direct grant.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../../users/user/classes/User.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### resolve()\n\n> **resolve**(`request`, `resolution`): `Promise`\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\nResolve a request belonging to this entity at an observed revision.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `request` | [`AccessRequest`](AccessRequest.md) |\n| `resolution` | [`ResolveRequest`](../../../../../generated/storage/types.gen/type-aliases/ResolveRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`AccessRequest`](../../../../../generated/storage/types.gen/type-aliases/AccessRequest.md)\\>\n\n***\n\n### state()\n\n> **state**(`offset?`): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) \\| `undefined`; `canReview`: `boolean`; `mine`: [`AccessRequest`](AccessRequest.md) \\| `undefined`; `nextOffset`: `number` \\| `undefined`; `owner`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; `pendingCount`: `number`; `requests`: [`AccessRequest`](AccessRequest.md)[]; `supportedLevels`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)[]; \\}\\>\n\nA page of access requests, including the caller's own request and review rights.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `offset?` | `number` |\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) \\| `undefined`; `canReview`: `boolean`; `mine`: [`AccessRequest`](AccessRequest.md) \\| `undefined`; `nextOffset`: `number` \\| `undefined`; `owner`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; `pendingCount`: `number`; `requests`: [`AccessRequest`](AccessRequest.md)[]; `supportedLevels`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md)[]; \\}\\>\n\n***\n\n### submit()\n\n> **submit**(`requestedLevel`, `revision?`): `Promise`\\<[`AccessRequest`](AccessRequest.md)\\>\n\nRequest access, optionally naming the revision of an earlier request.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `requestedLevel` | [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md) |\n| `revision?` | `number` |\n\n#### Returns\n\n`Promise`\\<[`AccessRequest`](AccessRequest.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `entity_id`: `string`; `entity_type`: [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md); \\}\n\nSerialize the entity reference without credentials.\n\n#### Returns\n\n\\{ `entity_id`: `string`; `entity_type`: [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md); \\}\n\n| Name | Type |\n| ------ | ------ |\n| `entity_id` | `string` |\n| `entity_type` | [`ShareEntityType`](../../../../../generated/storage/types.gen/type-aliases/ShareEntityType.md) |\n\n\n<!-- src/entities/sharing/permissions/functions/sharePermissionBody.md -->\n# Function: sharePermissionBody()\n\n> **sharePermissionBody**(`options`): [`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md)\n\nConvert sharing options into the generated backend contract.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SharePermissionOptions`](../type-aliases/SharePermissionOptions.md) |\n\n## Returns\n\n[`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md)\n\n\n<!-- src/entities/sharing/permissions/type-aliases/SharePermissionOptions.md -->\n# Type Alias: SharePermissionOptions\n\n> **SharePermissionOptions** = `Omit`\\<[`UpdateSharePermissionRequestV2`](../../../../../generated/storage/types.gen/type-aliases/UpdateSharePermissionRequestV2.md), `\"channelSharePermissions\"`\\> & \\{ `channelSharePermissions?`: \\{ `accessLevel?`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `channel`: [`Channel`](../../../channels/channel/classes/Channel.md); `operation`: [`UpdateChannelSharePermission`](../../../../../generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md)\\[`\"operation\"`\\]; \\}[] \\| `null`; \\}\n\nSharing updates reference channels by handle. Null clears the corresponding grant collection.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `channelSharePermissions?` | \\{ `accessLevel?`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `channel`: [`Channel`](../../../channels/channel/classes/Channel.md); `operation`: [`UpdateChannelSharePermission`](../../../../../generated/storage/types.gen/type-aliases/UpdateChannelSharePermission.md)\\[`\"operation\"`\\]; \\}[] \\| `null` | Channel grants to create or replace. |\n\n\n<!-- src/events/receiver/classes/MacroEvents.md -->\n# Class: MacroEvents\n\nPer-instance event receiver. Subscribe with [MacroEvents.on](#on), then\neither [MacroEvents.listen](#listen) (SSE, the default) or mount\n[MacroEvents.webhook](#webhook) at a persisted webhook URL.\n\nObtain via `macro.events` — do not construct directly.\n\n## Constructors\n\n### Constructor\n\n> **new MacroEvents**(`client`, `secret?`): `MacroEvents`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `secret?` | `string` |\n\n#### Returns\n\n`MacroEvents`\n\n## Methods\n\n### handle()\n\n> **handle**(`rawBody`, `headers`): `Promise`\\<`void`\\>\n\nFeed a raw webhook delivery in: verifies the signature, parses, and\ndispatches to matching handlers.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `rawBody` | `string` |\n| `headers` | `DeliveryHeaders` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Throws\n\nif no signing secret was configured, or if the\n signature is missing or invalid.\n\n***\n\n### listen()\n\n> **listen**(`opts?`): `Promise`\\<() => `void`\\>\n\nOpen a live Server-Sent Events stream of matching broker events. This is\nthe default way to receive events — no public URL or signing secret\nrequired. Delivery is best-effort: events published before the\nconnection, while disconnected, or dropped for a slow subscriber are\nmissed; there is no replay.\n\nFilters default to the event names currently registered with [on](#on).\nThe stream uses those filters for its lifetime; later `.on` / unsubscribe\ncalls do not change what the server sends.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | [`ListenOptions`](../interfaces/ListenOptions.md) |\n\n#### Returns\n\n`Promise`\\<() => `void`\\>\n\nA function that closes the stream.\n\n***\n\n### on()\n\n> **on**\\<`E`\\>(`event`, `handler`): () => `void`\n\nSubscribe to an event across all entities.\n\n#### Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-e\"></a> `E` *extends* `\"agent_session.opened\"` \\| `\"agent_session.turn_started\"` \\| `\"agent_session.turn_ended\"` \\| `\"agent_session.command_rejected\"` \\| `\"agent_session.settled\"` \\| `\"agent_session.waiting_for_input\"` \\| `\"agent_session.input_received\"` \\| `\"agent_session.mentioned\"` \\| `\"agent_session.stopped\"` \\| `\"agent_session.renamed\"` \\| `\"agent_session.deleted\"` \\| `\"channel.picture_changed\"` \\| `\"channel.created\"` \\| `\"channel.updated\"` \\| `\"channel.deleted\"` \\| `\"channel.participant_added\"` \\| `\"channel.participant_removed\"` \\| `\"document.created\"` \\| `\"document.updated\"` \\| `\"document.deleted\"` \\| `\"document.content_uploaded\"` \\| `\"document.sync_content_updated\"` \\| `\"document.purged\"` \\| `\"document.copied\"` \\| `\"document.interaction\"` \\| `\"message.posted\"` \\| `\"message.patched\"` \\| `\"message.deleted\"` \\| `\"message.mentioned\"` \\| `\"message.attachment_created\"` \\| `\"message.attachment_removed\"` |\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `event` | `E` |\n| `handler` | `EventHandler`\\<`E`\\> |\n\n#### Returns\n\nAn unsubscribe function.\n\n() => `void`\n\n***\n\n### onSelfMention()\n\n> **onSelfMention**(`handler`): () => `void`\n\nSubscribe to @-mentions of the authenticated caller: `message.mentioned`\ndeliveries whose mentioned entity is this bot (bot auth) or this user\n(user auth), in channels and in document comments alike.\n\n`message.mentioned` deliveries cover every mention the stream's (or\nwebhook's) workspace can access (its `ids` filter holds channel or\ndocument ids); picking out \"me\" happens here, client-side. The caller's\nidentity is resolved lazily (once) on the first delivery.\n\nFor SSE, register this handler before [listen](#listen) so the derived\nfilters include `message.mentioned`. For persisted webhooks, register the\nwebhook separately, e.g. `macro.webhooks.create({ filters: [{ events:\n['message.mentioned'] }], … })`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `handler` | `EventHandler`\\<`\"message.mentioned\"`\\> |\n\n#### Returns\n\nAn unsubscribe function.\n\n() => `void`\n\n***\n\n### webhook()\n\n> **webhook**(): (`req`) => `Promise`\\<`Response`\\>\n\nA Fetch-style handler to mount at your persisted webhook route.\n\nRequires `webhookSecret` (or `MACRO_WEBHOOK_SECRET`).\n\n#### Returns\n\n(`req`) => `Promise`\\<`Response`\\>\n\n#### Example\n\n```ts\napp.post('/webhook', macro.events.webhook()); // Hono\n```\n\n\n<!-- src/events/receiver/interfaces/ListenOptions.md -->\n# Interface: ListenOptions\n\nOptions for [MacroEvents.listen](../classes/MacroEvents.md#listen).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-filters\"></a> `filters?` | [`WebhookFilter`](../../../../generated/storage/types.gen/type-aliases/WebhookFilter.md)[] | Event/entity-id filters, identical to persisted webhook `filters`. Defaults to one filter covering every event currently registered with [MacroEvents.on](../classes/MacroEvents.md#on). |\n| <a id=\"property-scope\"></a> `scope?` | [`WebhookScope`](../../../../generated/storage/types.gen/type-aliases/WebhookScope.md) | Personal or team workspace whose webhook lifecycle events are delivered. Defaults to `'user'`. |\n| <a id=\"property-signal\"></a> `signal?` | `AbortSignal` | Abort the stream. |\n\n\n<!-- src/macro/classes/Macro.md -->\n# Class: Macro\\<T\\>\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` *extends* [`MacroOpts`](../../config/interfaces/MacroOpts.md) | [`MacroOpts`](../../config/interfaces/MacroOpts.md) |\n\n## Constructors\n\n### Constructor\n\n> **new Macro**\\<`T`\\>(`opts`): `Macro`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | `T` |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-_client\"></a> `_client` | `readonly` | `MacroClient` | Direct access to the underlying hey-api service clients. |\n| <a id=\"property-agents\"></a> `agents` | `readonly` | [`AgentNamespace`](../../entities/agents/namespace/classes/AgentNamespace.md) | agents resources and operations. |\n| <a id=\"property-agentsessions\"></a> `agentSessions` | `readonly` | [`AgentSessionNamespace`](../../entities/agent-sessions/namespace/classes/AgentSessionNamespace.md) | - |\n| <a id=\"property-ai\"></a> `ai` | `readonly` | [`AiNamespace`](../../entities/ai/namespace/classes/AiNamespace.md) | - |\n| <a id=\"property-apikeys\"></a> `apiKeys` | `readonly` | [`ApiKeyNamespace`](../../entities/api-keys/namespace/classes/ApiKeyNamespace.md) | apiKeys resources and operations. |\n| <a id=\"property-bots\"></a> `bots` | `readonly` | [`BotsNamespace`](../../entities/bots/namespace/classes/BotsNamespace.md) | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | [`CalendarNamespace`](../../entities/calendar/namespace/classes/CalendarNamespace.md) | - |\n| <a id=\"property-calls\"></a> `calls` | `readonly` | [`CallRecordNamespace`](../../entities/calls/namespace/classes/CallRecordNamespace.md) | - |\n| <a id=\"property-channels\"></a> `channels` | `readonly` | [`ChannelNamespace`](../../entities/channels/namespace/classes/ChannelNamespace.md) | - |\n| <a id=\"property-crm\"></a> `crm` | `readonly` | [`CrmNamespace`](../../entities/crm/namespace/classes/CrmNamespace.md) | - |\n| <a id=\"property-databases\"></a> `databases` | `readonly` | [`DatabaseNamespace`](../../entities/databases/namespace/classes/DatabaseNamespace.md) | - |\n| <a id=\"property-documents\"></a> `documents` | `readonly` | [`DocumentNamespace`](../../entities/documents/namespace/classes/DocumentNamespace.md) | - |\n| <a id=\"property-email\"></a> `email` | `readonly` | [`EmailNamespace`](../../entities/email/namespace/classes/EmailNamespace.md) | - |\n| <a id=\"property-entitymentions\"></a> `entityMentions` | `readonly` | [`EntityMentionNamespace`](../../entities/entity-mentions/namespace/classes/EntityMentionNamespace.md) | entityMentions resources and operations. |\n| <a id=\"property-events\"></a> `events` | `readonly` | [`MacroEvents`](../../events/receiver/classes/MacroEvents.md) | - |\n| <a id=\"property-favorites\"></a> `favorites` | `readonly` | [`FavoritesNamespace`](../../entities/favorites/namespace/classes/FavoritesNamespace.md) | - |\n| <a id=\"property-foreignentities\"></a> `foreignEntities` | `readonly` | [`ForeignEntityNamespace`](../../entities/foreign/namespace/classes/ForeignEntityNamespace.md) | - |\n| <a id=\"property-forms\"></a> `forms` | `readonly` | [`FormNamespace`](../../entities/forms/namespace/classes/FormNamespace.md) | Build forms and submit answers without granting respondents database access. |\n| <a id=\"property-githubpullrequests\"></a> `githubPullRequests` | `readonly` | [`GithubPullRequestNamespace`](../../entities/github-pull-requests/namespace/classes/GithubPullRequestNamespace.md) | githubPullRequests resources and operations. |\n| <a id=\"property-harnesses\"></a> `harnesses` | `readonly` | [`HarnessNamespace`](../../entities/harnesses/namespace/classes/HarnessNamespace.md) | harnesses resources and operations. |\n| <a id=\"property-initiatives\"></a> `initiatives` | `readonly` | [`InitiativeNamespace`](../../entities/initiatives/namespace/classes/InitiativeNamespace.md) | initiatives resources and operations. |\n| <a id=\"property-meetings\"></a> `meetings` | `readonly` | [`MeetingNamespace`](../../entities/meetings/namespace/classes/MeetingNamespace.md) | meetings resources and operations. |\n| <a id=\"property-notifications\"></a> `notifications` | `readonly` | [`NotificationNamespace`](../../entities/notifications/namespace/classes/NotificationNamespace.md) | - |\n| <a id=\"property-pins\"></a> `pins` | `readonly` | [`PinsNamespace`](../../entities/pins/namespace/classes/PinsNamespace.md) | - |\n| <a id=\"property-projects\"></a> `projects` | `readonly` | [`ProjectNamespace`](../../entities/projects/namespace/classes/ProjectNamespace.md) | - |\n| <a id=\"property-properties\"></a> `properties` | `readonly` | [`PropertiesNamespace`](../../entities/properties/namespace/classes/PropertiesNamespace.md) | - |\n| <a id=\"property-routines\"></a> `routines` | `readonly` | [`RoutineNamespace`](../../entities/routines/namespace/classes/RoutineNamespace.md) | routines resources and operations. |\n| <a id=\"property-tasks\"></a> `tasks` | `readonly` | [`TaskNamespace`](../../entities/tasks/namespace/classes/TaskNamespace.md) | - |\n| <a id=\"property-teams\"></a> `teams` | `readonly` | [`TeamNamespace`](../../entities/teams/namespace/classes/TeamNamespace.md) | - |\n| <a id=\"property-unfurls\"></a> `unfurls` | `readonly` | [`UnfurlNamespace`](../../entities/unfurls/namespace/classes/UnfurlNamespace.md) | unfurls resources and operations. |\n| <a id=\"property-users\"></a> `users` | `readonly` | [`UserNamespace`](../../entities/users/namespace/classes/UserNamespace.md) | - |\n| <a id=\"property-webappurl\"></a> `webAppUrl` | `readonly` | `string` | Base URL of the Macro web app, used to build entity URLs. |\n| <a id=\"property-webhooks\"></a> `webhooks` | `readonly` | [`WebhooksNamespace`](../../entities/webhooks/namespace/classes/WebhooksNamespace.md) | - |\n\n## Methods\n\n### myPrincipalId()\n\n> **myPrincipalId**(): `Promise`\\<`string`\\>\n\nThe authenticated caller's mentionable principal — `bot|<uuid>` for bot\nauth, `macro|<email>` for user auth — fetched once and cached.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### requestedAs()\n\n> **requestedAs**(`user`): `Macro`\\<`T`\\>\n\nClone of this SDK acting on behalf of `user` (sent as\n`x-macro-bot-for-macro-user-id`). Bot auth only — throws for user auth,\nsince a user token always acts as its own user.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `user` | [`User`](../../entities/users/user/classes/User.md) |\n\n#### Returns\n\n`Macro`\\<`T`\\>\n\n\n<!-- src/macro/type-aliases/RequestActivity.md -->\n# Type Alias: RequestActivity\n\n> **RequestActivity** = \\{ `id`: `number`; `operation`: `string`; `service`: `string`; `status`: `\"started\"` \\| `\"completed\"` \\| `\"failed\"`; \\}\n\nA generated SDK operation lifecycle. Contains no arguments, URLs or response data.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-operation\"></a> `operation` | `string` |\n| <a id=\"property-service\"></a> `service` | `string` |\n| <a id=\"property-status\"></a> `status` | `\"started\"` \\| `\"completed\"` \\| `\"failed\"` |\n\n\n<!-- src/mentions/functions/msg.md -->\n# Function: msg()\n\n> **msg**(`strings`, ...`values`): [`RichMessage`](../interfaces/RichMessage.md)\n\nCompose a rich message. Interpolate mentions (a User, Document,\n[here](../variables/here.md), …) or plain strings. Each mention writes its `<m-*>` tag into the\ncontent *and* adds itself to `mentions[]`, so the two can never drift; strings\nare inserted as-is, so markdown like `**bold**` passes through untouched.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `strings` | `TemplateStringsArray` |\n| ...`values` | [`Interpolation`](../type-aliases/Interpolation.md)[] |\n\n## Returns\n\n[`RichMessage`](../interfaces/RichMessage.md)\n\n## Example\n\n```ts\nchannel.send(msg`Hey ${user}, see ${doc}. cc ${here}`);\nchannel.send(msg`Status: ${status} — see ${doc}`);\n```\n\n\n<!-- src/mentions/functions/toBody.md -->\n# Function: toBody()\n\n> **toBody**(`body`): [`RichMessage`](../interfaces/RichMessage.md)\n\nNormalize a plain string or a [RichMessage](../interfaces/RichMessage.md) to the wire shape.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../interfaces/RichMessage.md) |\n\n## Returns\n\n[`RichMessage`](../interfaces/RichMessage.md)\n\n\n<!-- src/mentions/functions/wrapXml.md -->\n# Function: wrapXml()\n\n> **wrapXml**(`tag`, `data`): `string`\n\nSerialize a mention node to its `<tag>{json}</tag>` wire form.\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `tag` | `string` |\n| `data` | `unknown` |\n\n## Returns\n\n`string`\n\n\n<!-- src/mentions/interfaces/MentionPart.md -->\n# Interface: MentionPart\n\nThe two things a mentionable entity contributes to a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-mention\"></a> `mention` | [`SimpleMention`](../../../generated/storage/types.gen/type-aliases/SimpleMention.md) | The parallel entry the backend uses for notifications and permissions. |\n| <a id=\"property-tag\"></a> `tag` | `string` | The `<m-*>` tag written into the message content. |\n\n\n<!-- src/mentions/interfaces/Mentionable.md -->\n# Interface: Mentionable\n\nAnything that can be dropped into a [msg](../functions/msg.md) template as a mention.\n\n## Methods\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](MentionPart.md)\n\n\n<!-- src/mentions/interfaces/RichMessage.md -->\n# Interface: RichMessage\n\nA composed message body: content with embedded tags, and the matching mentions.\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-content\"></a> `content` | `string` |\n| <a id=\"property-mentions\"></a> `mentions` | [`SimpleMention`](../../../generated/storage/types.gen/type-aliases/SimpleMention.md)[] |\n\n\n<!-- src/mentions/type-aliases/Interpolation.md -->\n# Type Alias: Interpolation\n\n> **Interpolation** = [`Mentionable`](../interfaces/Mentionable.md) \\| `string` \\| `number`\n\nWhat may be interpolated into a [msg](../functions/msg.md) template: a mention, or plain text.\n\n\n<!-- src/mentions/variables/here.md -->\n# Variable: here\n\n> `const` **here**: [`Mentionable`](../interfaces/Mentionable.md)\n\nThe `@here` group mention.\n\n\n<!-- src/utils/lazy/classes/Lazy.md -->\n# Class: Lazy\\<T\\>\n\nA value fetched on first access and cached thereafter. Powers thin entity\nhandles: construction is free, the record is loaded lazily the first time a\nfield is read, and concurrent reads share one in-flight request. Pass a\n`seed` when the record is already known (from a list or an event) to skip the\nfetch entirely.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-t\"></a> `T` |\n\n## Constructors\n\n### Constructor\n\n> **new Lazy**\\<`T`\\>(`loader`, `seed?`): `Lazy`\\<`T`\\>\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `loader` | () => `Promise`\\<`T`\\> |\n| `seed?` | `T` |\n\n#### Returns\n\n`Lazy`\\<`T`\\>\n\n## Methods\n\n### clear()\n\n> **clear**(): `void`\n\nDrop the cached value so the next read refetches.\n\n#### Returns\n\n`void`\n\n***\n\n### get()\n\n> **get**(): `Promise`\\<`T`\\>\n\n#### Returns\n\n`Promise`\\<`T`\\>\n\n***\n\n### peek()\n\n> **peek**(): `T` \\| `undefined`\n\nThe cached value, if already loaded — never triggers a fetch.\n\n#### Returns\n\n`T` \\| `undefined`\n\n\n<!-- src/utils/pagination/functions/paginate.md -->\n# Function: paginate()\n\n> **paginate**\\<`T`, `Cursor`\\>(`fetchPage`): `AsyncGenerator`\\<`T`\\>\n\nAsync generator over a cursor-paginated API. Iterate with `for await`.\nCursors are plain JSON values (strings or small objects), so a page whose\nnext cursor serialises identically to the one it was fetched with means the\nserver is not advancing; the generator throws instead of looping forever.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` | - |\n| <a id=\"type-parameter-cursor\"></a> `Cursor` | `string` |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `fetchPage` | (`cursor?`) => `Promise`\\<[`Page`](../interfaces/Page.md)\\<`T`, `Cursor`\\>\\> |\n\n## Returns\n\n`AsyncGenerator`\\<`T`\\>\n\n\n<!-- src/utils/pagination/interfaces/Page.md -->\n# Interface: Page\\<T, Cursor\\>\n\nOne page of a cursor-paginated list.\n\n## Type Parameters\n\n| Type Parameter | Default type |\n| ------ | ------ |\n| <a id=\"type-parameter-t\"></a> `T` | - |\n| <a id=\"type-parameter-cursor\"></a> `Cursor` | `string` |\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-items\"></a> `items` | `T`[] |\n| <a id=\"property-nextcursor\"></a> `nextCursor?` | `Cursor` \\| `null` |\n\n\n<!-- src/utils/unwrap/classes/MacroApiError.md -->\n# Class: MacroApiError\n\nA non-2xx HTTP response (Macro API, or a raw fetch like presigned downloads).\n\n## Extends\n\n- [`MacroError`](MacroError.md)\n\n## Extended by\n\n- [`MacroOpRefusedError`](../../../entities/databases/database/classes/MacroOpRefusedError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroApiError**(`status`, `data`): `MacroApiError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `status` | `number` |\n| `data` | `unknown` |\n\n#### Returns\n\n`MacroApiError`\n\n#### Overrides\n\n[`MacroError`](MacroError.md).[`constructor`](MacroError.md#constructor)\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-data\"></a> `data` | `readonly` | `unknown` |\n| <a id=\"property-status\"></a> `status` | `readonly` | `number` |\n\n\n<!-- src/utils/unwrap/classes/MacroError.md -->\n# Class: MacroError\n\nBase for every error the SDK throws.\n\n## Extends\n\n- `Error`\n\n## Extended by\n\n- [`MacroApiError`](MacroApiError.md)\n- [`MacroNotFoundError`](MacroNotFoundError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroError**(`message`): `MacroError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `message` | `string` |\n\n#### Returns\n\n`MacroError`\n\n#### Overrides\n\n`Error.constructor`\n\n\n<!-- src/utils/unwrap/classes/MacroNotFoundError.md -->\n# Class: MacroNotFoundError\n\nThe API succeeded but the addressed entity doesn't exist in the result.\n\n## Extends\n\n- [`MacroError`](MacroError.md)\n\n## Constructors\n\n### Constructor\n\n> **new MacroNotFoundError**(`message`): `MacroNotFoundError`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `message` | `string` |\n\n#### Returns\n\n`MacroNotFoundError`\n\n#### Overrides\n\n[`MacroError`](MacroError.md).[`constructor`](MacroError.md#constructor)\n\n\n<!-- src/utils/unwrap/functions/unwrap.md -->\n# Function: unwrap()\n\n> **unwrap**\\<`TData`, `TError`\\>(`res`): `TData`\n\nTurn a hey-api `{ data, error, response? }` result into either the success\npayload or a thrown MacroApiError.\n\n## Type Parameters\n\n| Type Parameter |\n| ------ |\n| <a id=\"type-parameter-tdata\"></a> `TData` |\n| <a id=\"type-parameter-terror\"></a> `TError` |\n\n## Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `res` | \\{ `data?`: `TData`; `error?`: `TError`; `response?`: `Response`; \\} |\n| `res.data?` | `TData` |\n| `res.error?` | `TError` |\n| `res.response?` | `Response` |\n\n## Returns\n\n`TData`\n"
}
]
diff --git a/crates/agent_code_mode/src/domain/service.rs b/crates/agent_code_mode/src/domain/service.rs
index 735a93e9e9..4e19812cdf 100644
--- a/crates/agent_code_mode/src/domain/service.rs
+++ b/crates/agent_code_mode/src/domain/service.rs
@@ -224,9 +224,7 @@ pub fn covered_by_code_sdk(name: &str, user_tool: bool) -> bool {
!user_tool
&& matches!(
name,
- "NameSearch"
- | "ListEntities"
- | "ReadContent"
+ "ReadContent"
| "ReadMetadata"
| "RenameDocument"
| "MoveToProject"
@@ -256,7 +254,6 @@ pub fn covered_by_code_sdk(name: &str, user_tool: bool) -> bool {
| "ReadChannelThread"
| "RenameChannel"
| "ManageChannelParticipants"
- | "ReadChat"
| "ReadCallRecord"
| "UpdateCallRecord"
| "DeleteCallRecord"
diff --git a/crates/agent_inmem/AGENTS.md b/crates/agent_inmem/AGENTS.md
index f4bfd54c40..2e1f184e85 100644
--- a/crates/agent_inmem/AGENTS.md
+++ b/crates/agent_inmem/AGENTS.md
@@ -46,6 +46,8 @@ milliseconds instead of waiting on container provisioning.
## Gotchas
+- Keep session-aware `NameSearch`, `ContentSearch`, and `ListEntities` native in
+ code mode; legacy `ReadChat` must not appear in either runtime tool catalog.
- Replay tool calls using `_meta.macro.toolName`; ACP titles may be human-readable
MCP labels, so only use the title for older frames without tool-name metadata.
diff --git a/crates/agent_inmem/src/outbound/rig_engine/test.rs b/crates/agent_inmem/src/outbound/rig_engine/test.rs
index b1cc60c681..902528fbab 100644
--- a/crates/agent_inmem/src/outbound/rig_engine/test.rs
+++ b/crates/agent_inmem/src/outbound/rig_engine/test.rs
@@ -84,12 +84,16 @@ fn reduced_definitions_keep_user_input_and_user_tool_review() {
for name in ["SendEmail", "CreateCalendarEvent"] {
assert!(selected.user_tools.contains_key(name));
}
- assert!(selected.tools.contains_key("ContentSearch"));
- assert!(!selected.tools.contains_key("NameSearch"));
+ for name in ["ContentSearch", "NameSearch", "ListEntities"] {
+ assert!(selected.tools.contains_key(name));
+ }
+ assert!(!selected.tools.contains_key("ReadChat"));
+ }
+ for name in ["ContentSearch", "NameSearch", "ListEntities"] {
+ assert!(tools.tool_names.contains(name));
+ assert!(!tools.deferred.iter().any(|tool| tool.name == name));
}
- assert!(tools.tool_names.contains("ContentSearch"));
- assert!(!tools.tool_names.contains("NameSearch"));
- assert!(!tools.deferred.iter().any(|tool| tool.name == "NameSearch"));
+ assert!(!tools.tool_names.contains("ReadChat"));
}
#[derive(Deserialize, JsonSchema)]
diff --git a/crates/agent_session/AGENTS.md b/crates/agent_session/AGENTS.md
index e6f4610d0d..db4199347c 100644
--- a/crates/agent_session/AGENTS.md
+++ b/crates/agent_session/AGENTS.md
@@ -15,6 +15,8 @@ consumer talks to.
- `src/domain/turn_state.rs` + `src/domain/control.rs`: per-turn state and
the control-plane commands (used by held tool-call approvals).
- `src/inbound/axum_router.rs`: the HTTP surface.
+- `src/domain/read.rs` and `src/inbound/toolset/read_agent_session.rs`: bounded,
+ view-authorized conversation reads using the shared transcript fold.
- `src/outbound/postgres.rs`: the session repository.
- `src/outbound/broker_lifecycle_publisher.rs` /
`broker_log_realtime.rs`: Kafka publication of lifecycle and log events.
@@ -29,8 +31,8 @@ consumer talks to.
## Boundaries
-- Depends on: `agent_runtime_protocol`, `agent_fold` (indirectly via
- callers), `teams`, `macro_authorization`.
+- Depends on: `agent_runtime_protocol`, `agent_fold`, `teams`,
+ `macro_authorization`.
- Used by: `agent_harness`, `agent_inmem`, `agent_egress`, `agent_trigger`,
`agent_changes`, `agent_session_realtime`, `ai_tools` (coding-agent
toolset), `complete_graph`, `webhook`, `search_service`, `soup_realtime`,
@@ -44,12 +46,19 @@ consumer talks to.
- Add a lifecycle transition: `src/domain/lifecycle.rs` → `src/domain/service.rs`
→ `src/outbound/broker_lifecycle_publisher.rs` if it should publish.
+## Tool contracts
+
+- `src/inbound/toolset/`: session reads, creation, lifecycle actions, and sharing. Mutations preserve acting-user identity and existing owner/edit receipts; internal controls accept only prompt/stop, never human approvals.
+
## Checks
- `cargo test -p agent_session` (`SQLX_OFFLINE` unset).
## Gotchas
+- `ReadAgentSession` bounds its response, not storage work: it folds the full
+ effective history like the app. Raw log limits break replay and turn numbering;
+ bounded reads need a persisted conversation projection or a fold-aware port.
- The row's fenced log writer and the Cursor projection both lock the
session row `FOR UPDATE`; never add a second `NOWAIT` locker without
checking both paths (see git history on `src/domain/control.rs`).
diff --git a/crates/agent_session/Cargo.toml b/crates/agent_session/Cargo.toml
index b16c765a75..7e9e0d8a2d 100644
--- a/crates/agent_session/Cargo.toml
+++ b/crates/agent_session/Cargo.toml
@@ -34,6 +34,7 @@ outbound = [
"dep:entity_registry_db_utils",
"dep:model-entity",
"dep:reqwest",
+ "dep:macro_tower_layers",
"dep:macro_authorization",
"dep:sqlx",
"dep:share_permission_db_utils",
@@ -88,6 +89,7 @@ macro_user_id = { path = "../macro_user_id" }
utoipa = { workspace = true, optional = true }
rootcause = { workspace = true }
reqwest = { workspace = true, optional = true }
+macro_tower_layers = { path = "../macro_tower_layers", optional = true }
uuid = { workspace = true }
sqlx = { workspace = true, features = ["json"], optional = true }
chrono = { workspace = true }
diff --git a/crates/agent_session/src/domain/coding_agents.rs b/crates/agent_session/src/domain/coding_agents.rs
index 2e322660e7..210473007c 100644
--- a/crates/agent_session/src/domain/coding_agents.rs
+++ b/crates/agent_session/src/domain/coding_agents.rs
@@ -120,6 +120,12 @@ pub trait CodingAgentService: Send + Sync + 'static {
user_id: MacroUserIdStr<'static>,
) -> Pin<Box<dyn Future<Output = Result<Vec<CodingAgent>, CodingAgentError>> + Send + '_>>;
+ /// Start a session with any available coding or chat persona the caller may use.
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>;
+
/// Reauthorize a persona, create a session, and admit its initial prompt once.
fn dispatch(
&self,
@@ -168,6 +174,26 @@ where
&self,
command: DispatchCodingAgentRequest,
) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ self.dispatch_selected(command, true)
+ }
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ self.dispatch_selected(command, false)
+ }
+}
+
+impl<Directory: CodingAgentDirectory, Sessions: RoutineSessions>
+ CodingAgentServiceImpl<Directory, Sessions>
+{
+ fn dispatch_selected(
+ &self,
+ command: DispatchCodingAgentRequest,
+ coding_only: bool,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
{
Box::pin(async move {
if command.prompt.trim().is_empty() {
@@ -176,9 +202,12 @@ where
// Re-read visibility and configuration at dispatch time. A saved tool
// result is not authority to use a removed or reconfigured persona.
let agent = self
- .list(command.user_id.clone())
+ .directory
+ .candidates(command.user_id.clone())
.await?
.into_iter()
+ .filter(|candidate| candidate.available && (!coding_only || candidate.is_coding))
+ .map(|candidate| candidate.agent)
.find(|agent| agent.id == command.agent_id)
.ok_or(CodingAgentError::Unavailable)?;
let session_id = AgentSessionId::new();
diff --git a/crates/agent_session/src/domain/coding_agents/test.rs b/crates/agent_session/src/domain/coding_agents/test.rs
index 9fb7a2443b..b20395679a 100644
--- a/crates/agent_session/src/domain/coding_agents/test.rs
+++ b/crates/agent_session/src/domain/coding_agents/test.rs
@@ -273,3 +273,25 @@ async fn a_different_accepted_action_does_not_report_dispatch_success() {
));
assert_eq!(sessions.prompted.lock().unwrap().len(), 1);
}
+
+#[tokio::test]
+async fn creation_accepts_chat_personas_but_coding_dispatch_stays_scoped() {
+ let (service, directory, sessions, _) = fixture();
+ let chat = candidate(false, true);
+ directory.candidates.lock().unwrap().push(chat.clone());
+ assert!(matches!(
+ service.dispatch(command(chat.agent.id)).await,
+ Err(CodingAgentError::Unavailable)
+ ));
+ assert!(sessions.prepared.lock().unwrap().is_empty());
+ let created = service.create(command(chat.agent.id)).await.unwrap();
+ assert_eq!(created.agent_id, chat.agent.id);
+ assert_eq!(sessions.prompted.lock().unwrap().len(), 1);
+ assert_eq!(sessions.prompted.lock().unwrap()[0].action.owner, user());
+ directory.candidates.lock().unwrap().clear();
+ assert!(matches!(
+ service.create(command(chat.agent.id)).await,
+ Err(CodingAgentError::Unavailable)
+ ));
+ assert_eq!(sessions.prompted.lock().unwrap().len(), 1);
+}
diff --git a/crates/agent_session/src/domain/mod.rs b/crates/agent_session/src/domain/mod.rs
index 76741cd573..2910fd8d64 100644
--- a/crates/agent_session/src/domain/mod.rs
+++ b/crates/agent_session/src/domain/mod.rs
@@ -15,6 +15,7 @@ pub mod name_generation;
pub mod ports;
pub mod pull_request;
pub mod pull_request_links;
+pub mod read;
mod sandbox_size;
pub mod search;
pub mod service;
@@ -45,3 +46,6 @@ pub mod warm;
/// Visibility policy for standalone session lists.
pub mod list_visibility;
+
+/// User-scoped AI session actions.
+pub mod tool_actions;
diff --git a/crates/agent_session/src/domain/read.rs b/crates/agent_session/src/domain/read.rs
new file mode 100644
index 0000000000..cdd524144e
--- /dev/null
+++ b/crates/agent_session/src/domain/read.rs
@@ -0,0 +1,162 @@
+//! Authorized conversation reads with bounded responses over the app's session fold.
+
+use agent_fold::domain::{fold::fold, model::FoldedMessage};
+use entity_access::domain::models::{EntityAccessReceipt, EntityType, ViewAccessLevel};
+use serde::Serialize;
+
+use super::{
+ error::{AgentSessionError, Result},
+ model::{AgentSession, AgentSessionId},
+ ports::{AgentSessionLogRepo, AgentSessionRepo},
+};
+
+const MAX_MESSAGES: usize = 20;
+const MAX_MESSAGE_CHARS: usize = 4_000;
+
+/// A readable session conversation, including tool activity and failures.
+#[derive(Debug, Serialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(rename_all = "camelCase")]
+pub struct SessionConversation {
+ /// Session identity.
+ pub session_id: uuid::Uuid,
+ /// User-facing session name.
+ pub name: String,
+ /// Owner's principal id.
+ pub owner_id: String,
+ /// Agent persona id.
+ pub bot_id: uuid::Uuid,
+ /// Whether the session is archived and read-only.
+ pub is_archived: bool,
+ /// Configured runtime.
+ pub harness: String,
+ /// Selected model.
+ pub model: String,
+ /// Last runtime status.
+ pub status: String,
+ /// Messages in the requested turn, or the latest messages, oldest first.
+ pub messages: Vec<SessionConversationMessage>,
+ /// Number of messages matching the requested turn before bounding.
+ pub total_messages: usize,
+ /// Whether older messages or text were omitted.
+ pub truncated: bool,
+}
+
+/// One folded prompt or reply.
+#[derive(Debug, Serialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(rename_all = "camelCase")]
+pub struct SessionConversationMessage {
+ /// Turn number; pass it back to read that turn specifically.
+ pub turn: u32,
+ /// Whether this message came from the user or agent.
+ pub role: SessionMessageRole,
+ /// Readable prose, tool activity, outputs, and errors.
+ pub content: String,
+ /// Terminal runtime error, retained separately even when earlier text is truncated.
+ pub failure: Option<String>,
+ /// Whether this message's text exceeded the character budget.
+ pub truncated: bool,
+}
+
+/// The two sides of a session conversation.
+#[derive(Debug, Serialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum SessionMessageRole {
+ /// A user prompt.
+ User,
+ /// An agent reply.
+ Agent,
+}
+
+/// Read-only use case over the session's existing persistence ports.
+#[derive(Clone)]
+pub struct SessionReader<R> {
+ repo: R,
+}
+
+impl<R> SessionReader<R> {
+ /// Compose the session repository at the application boundary.
+ pub fn new(repo: R) -> Self {
+ Self { repo }
+ }
+}
+
+impl<R: AgentSessionRepo + AgentSessionLogRepo> SessionReader<R> {
+ /// Read only the session named by a verified view-access capability.
+ #[tracing::instrument(name = "agent_session.read_conversation", skip_all, fields(session_id = %access.entity().entity_id), err)]
+ pub async fn read(
+ &self,
+ access: EntityAccessReceipt<ViewAccessLevel>,
+ turn: Option<u32>,
+ ) -> Result<SessionConversation> {
+ if access.entity().entity_type != EntityType::AgentSession {
+ return Err(AgentSessionError::Forbidden);
+ }
+ let id = uuid::Uuid::parse_str(&access.entity().entity_id)
+ .map_err(|_| AgentSessionError::Forbidden)?;
+ let session_id = AgentSessionId::new_from_uuid(id);
+ let session = self.repo.get(session_id).await?;
+ let log = AgentSessionLogRepo::list_by_session(&self.repo, session_id).await?;
+ let messages = fold(log.into_iter().map(|entry| entry.entry));
+ Ok(conversation(&session, messages, turn))
+ }
+}
+
+fn conversation(
+ session: &AgentSession,
+ messages: Vec<FoldedMessage>,
+ turn: Option<u32>,
+) -> SessionConversation {
+ let matching: Vec<_> = messages
+ .into_iter()
+ .filter(|message| turn.is_none_or(|turn| message.id.0 == turn))
+ .collect();
+ let total_messages = matching.len();
+ let messages: Vec<_> = matching
+ .into_iter()
+ .skip(total_messages.saturating_sub(MAX_MESSAGES))
+ .map(|message| {
+ let text = message.searchable_text();
+ let content: String = text.chars().take(MAX_MESSAGE_CHARS).collect();
+ let (failure, failure_truncated) = match &message.stop {
+ Some(agent_fold::domain::model::StopReason::Failed { message, .. }) => {
+ let failure: String = message.chars().take(MAX_MESSAGE_CHARS).collect();
+ let truncated = failure.len() < message.len();
+ (Some(failure), truncated)
+ }
+ _ => (None, false),
+ };
+ SessionConversationMessage {
+ turn: message.id.0,
+ role: match message.author {
+ agent_fold::domain::model::Author::User { .. } => SessionMessageRole::User,
+ agent_fold::domain::model::Author::Agent => SessionMessageRole::Agent,
+ },
+ truncated: content.len() < text.len() || failure_truncated,
+ content,
+ failure,
+ }
+ })
+ .collect();
+ SessionConversation {
+ session_id: session.id.as_uuid(),
+ name: session.name.clone(),
+ owner_id: session.owner_id.to_string(),
+ bot_id: session.bot_id.as_uuid(),
+ is_archived: session.is_archived,
+ harness: session.harness.clone(),
+ model: session.model.clone(),
+ status: match &session.status {
+ super::model::SessionStatus::Event(event) => event.as_str().to_string(),
+ status => status.as_ref().to_string(),
+ },
+ truncated: messages.len() < total_messages || messages.iter().any(|m| m.truncated),
+ messages,
+ total_messages,
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/agent_session/src/domain/read/test.rs b/crates/agent_session/src/domain/read/test.rs
new file mode 100644
index 0000000000..8c3c1d0016
--- /dev/null
+++ b/crates/agent_session/src/domain/read/test.rs
@@ -0,0 +1,139 @@
+use super::*;
+use crate::testing::{InMemoryAgentSessionRepo, test_agent_session};
+use agent_fold::testing::{TURN, parse_log_as};
+use entity_access::domain::models::{AccessLevel, Entity, EntityPermission};
+use macro_user_id::user_id::MacroUserIdStr;
+
+#[tokio::test]
+async fn reads_only_the_authorized_session_and_folds_streamed_chunks() {
+ let repo = InMemoryAgentSessionRepo::new();
+ let session = AgentSessionId::TEST_A;
+ repo.insert_session(test_agent_session(session));
+ repo.extend_log(parse_log_as(session, TURN));
+ repo.extend_log(parse_log_as(
+ AgentSessionId::TEST_B,
+ &TURN.replace("list the examples", "PRIVATE OTHER SESSION"),
+ ));
+ let access = EntityAccessReceipt::try_new_authenticated_user(
+ MacroUserIdStr::try_from_email("[email protected]").expect("viewer"),
+ Entity {
+ entity_id: session.to_string(),
+ entity_type: EntityType::AgentSession,
+ },
+ EntityPermission::AccessLevel {
+ access_level: AccessLevel::View,
+ },
+ )
+ .expect("view receipt");
+ let result = SessionReader::new(repo)
+ .read(access, None)
+ .await
+ .expect("conversation");
+ assert_eq!(result.messages.len(), 2);
+ assert_eq!(
+ result.messages[0].content,
+ "list the examples and write a file"
+ );
+ assert!(result.messages[1].content.contains("Sure, "));
+ assert!(
+ !serde_json::to_string(&result)
+ .expect("json")
+ .contains("PRIVATE OTHER SESSION")
+ );
+ assert!(!result.truncated);
+}
+
+#[tokio::test]
+async fn refuses_a_receipt_for_another_entity_type_before_reading_storage() {
+ let repo = InMemoryAgentSessionRepo::new();
+ let access = EntityAccessReceipt::try_new_authenticated_user(
+ MacroUserIdStr::try_from_email("[email protected]").expect("viewer"),
+ Entity {
+ entity_id: AgentSessionId::TEST_A.to_string(),
+ entity_type: EntityType::Document,
+ },
+ EntityPermission::AccessLevel {
+ access_level: AccessLevel::View,
+ },
+ )
+ .expect("view receipt");
+ let result = SessionReader::new(repo.clone()).read(access, None).await;
+ assert!(matches!(result, Err(AgentSessionError::Forbidden)));
+ assert_eq!(repo.session_reads(), 0);
+ assert_eq!(repo.log_reads(), 0);
+}
+
+#[test]
+fn keeps_recent_history_and_allows_selecting_an_earlier_turn() {
+ let mut messages = Vec::new();
+ for turn in 0..15 {
+ let mut pair = fold(parse_log_as(AgentSessionId::TEST_A, TURN));
+ for message in &mut pair {
+ message.id.0 = turn;
+ }
+ messages.extend(pair);
+ }
+ let recent = conversation(
+ &test_agent_session(AgentSessionId::TEST_A),
+ messages.clone(),
+ None,
+ );
+ assert_eq!(recent.total_messages, 30);
+ assert_eq!(recent.messages.len(), 20);
+ assert_eq!(recent.messages[0].turn, 5);
+ assert_eq!(recent.messages[19].turn, 14);
+ assert!(recent.truncated);
+ let earlier = conversation(
+ &test_agent_session(AgentSessionId::TEST_A),
+ messages,
+ Some(2),
+ );
+ assert_eq!(earlier.messages.len(), 2);
+ assert!(earlier.messages.iter().all(|message| message.turn == 2));
+ assert!(!earlier.truncated);
+}
+
+#[test]
+fn preserves_failures_and_bounds_unicode_text_without_splitting_characters() {
+ let mut messages = fold(parse_log_as(AgentSessionId::TEST_A, TURN));
+ messages[1].parts =
+ non_empty::NonEmpty::new(vec![agent_fold::domain::model::MessagePart::Text {
+ text: "🦀".repeat(4_001),
+ }])
+ .expect("one part");
+ messages[1].stop = Some(agent_fold::domain::model::StopReason::Failed {
+ message: "Unknown tool mcp__missing".into(),
+ notice: None,
+ });
+ let result = conversation(&test_agent_session(AgentSessionId::TEST_A), messages, None);
+ assert_eq!(
+ result.messages[1].failure.as_deref(),
+ Some("Unknown tool mcp__missing")
+ );
+ assert!(result.messages[1].truncated);
+ let text = TURN.replace("list the examples and write a file", &"🦀".repeat(4_001));
+ let result = conversation(
+ &test_agent_session(AgentSessionId::TEST_A),
+ fold(parse_log_as(AgentSessionId::TEST_A, &text)),
+ None,
+ );
+ assert_eq!(result.messages[0].content.chars().count(), 4_000);
+ assert!(result.messages[0].truncated);
+ assert!(result.truncated);
+}
+
+#[test]
+fn reports_truncated_failures_even_when_search_text_omits_them() {
+ let mut messages = fold(parse_log_as(AgentSessionId::TEST_A, TURN));
+ messages[1].stop = Some(agent_fold::domain::model::StopReason::Failed {
+ message: " ".repeat(MAX_MESSAGE_CHARS + 1),
+ notice: None,
+ });
+ let result = conversation(&test_agent_session(AgentSessionId::TEST_A), messages, None);
+ assert_eq!(
+ result.messages[1].failure.as_deref(),
+ Some(" ".repeat(MAX_MESSAGE_CHARS).as_str())
+ );
+ assert!(result.messages[1].truncated);
+ assert!(result.truncated);
+}
diff --git a/crates/agent_session/src/domain/tool_actions.rs b/crates/agent_session/src/domain/tool_actions.rs
new file mode 100644
index 0000000000..edd07cb6e6
--- /dev/null
+++ b/crates/agent_session/src/domain/tool_actions.rs
@@ -0,0 +1,87 @@
+//! Curated session actions; the harness domain services enforce lifecycle and sharing policy.
+
+use macro_user_id::user_id::MacroUserIdStr;
+use serde::{Deserialize, Serialize};
+use std::pin::Pin;
+use uuid::Uuid;
+
+/// Session lifecycle actions available to agents. Human approvals are deliberately absent.
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
+pub enum SessionAction {
+ /// Rename a session you own.
+ Rename {
+ /// New display name.
+ name: String,
+ },
+ /// Archive or unarchive a session you own. Active private conversations cannot be archived.
+ Archive {
+ /// Whether the session should be archived.
+ archived: bool,
+ },
+ /// Delete a session you own and release its runtime resources.
+ Delete,
+ /// Send a follow-up prompt. Returns acceptance, not the agent's completed work.
+ Prompt {
+ /// Self-contained message to the agent.
+ prompt: String,
+ },
+ /// Stop the current turn without deleting the session.
+ Stop,
+}
+
+/// Delivery state of an accepted control.
+#[derive(Debug, Serialize, Deserialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum SessionControlStatus {
+ /// Forwarded to the running agent.
+ Sent,
+ /// Saved until the agent can receive it.
+ Queued,
+}
+
+/// A safely attributable action result.
+#[derive(Debug, Serialize, Deserialize)]
+#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
+#[serde(rename_all = "camelCase")]
+pub struct SessionActionResult {
+ /// Session acted on.
+ pub session_id: Uuid,
+ /// Human-readable outcome.
+ pub message: String,
+ /// Accepted prompt or stop id, when applicable.
+ pub action_id: Option<Uuid>,
+ /// Whether a control was sent or queued.
+ pub status: Option<SessionControlStatus>,
+}
+
+/// Safe failure text; transport failures never imply that a mutation did not happen.
+#[derive(Debug, thiserror::Error)]
+pub enum SessionActionError {
+ /// Missing or insufficient access.
+ #[error("Session unavailable or you do not have permission for this action.")]
+ Forbidden,
+ /// Domain refused the command.
+ #[error(
+ "Session action was refused. Check the session state, ownership, and sharing settings; archived sessions cannot be prompted or renamed."
+ )]
+ Rejected,
+ /// Delivery or response is uncertain.
+ #[error(
+ "Session action could not be confirmed. Read the session before retrying; do not automatically resend a prompt."
+ )]
+ Unconfirmed,
+}
+
+/// Session mutations routed to the service that owns the runtime.
+pub trait SessionActions: Send + Sync + 'static {
+ /// Execute with the verified tool caller's identity, never an AI-supplied user id.
+ fn execute(
+ &self,
+ user: MacroUserIdStr<'static>,
+ session_id: Uuid,
+ action: SessionAction,
+ ) -> Pin<Box<dyn Future<Output = Result<SessionActionResult, SessionActionError>> + Send + '_>>;
+}
diff --git a/crates/agent_session/src/inbound/axum_router.rs b/crates/agent_session/src/inbound/axum_router.rs
index 6b807539fb..56903d3d05 100644
--- a/crates/agent_session/src/inbound/axum_router.rs
+++ b/crates/agent_session/src/inbound/axum_router.rs
@@ -2403,3 +2403,6 @@ pub async fn warm_agent_session_handler<
session: session.map(|session| AgentSessionResponse::new(session, true)),
}))
}
+
+/// Internal service controls used by AI tools.
+pub mod tool_actions;
diff --git a/crates/agent_session/src/inbound/axum_router/test.rs b/crates/agent_session/src/inbound/axum_router/test.rs
index 91c4cce50a..946da9c4bd 100644
--- a/crates/agent_session/src/inbound/axum_router/test.rs
+++ b/crates/agent_session/src/inbound/axum_router/test.rs
@@ -1461,3 +1461,5 @@ async fn macrod_rejects_an_unsupported_base_before_dispatch() {
assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
assert!(requests.requested.lock().unwrap().is_empty());
}
+
+mod tool_actions;
diff --git a/crates/agent_session/src/inbound/axum_router/test/tool_actions.rs b/crates/agent_session/src/inbound/axum_router/test/tool_actions.rs
new file mode 100644
index 0000000000..335069c60f
--- /dev/null
+++ b/crates/agent_session/src/inbound/axum_router/test/tool_actions.rs
@@ -0,0 +1,344 @@
+use super::*;
+use crate::domain::error::Result as SessionResult;
+use crate::domain::ports::{AcceptedControl, QueuedControl};
+use entity_access::domain::models::{
+ AccessError, AccessLevel, BotAccessScope, CallChannelInfo, EntityAccessReceipt,
+ EntityPermission, EntityType, RequiredPermission, TeamRole, UserTeamInfo,
+};
+use macro_authorization::{INTERNAL_API_KEY_HEADER, INTERNAL_MACRO_USER_ID_HEADER};
+use macro_user_id::{lowercased::Lowercase, user_id::MacroUserId};
+use shared_entity_registry::OwnedPurgeOutcome;
+
+#[derive(Default)]
+struct Controls {
+ deleted: Mutex<Vec<AgentSessionId>>,
+ controls: Mutex<Vec<(AgentSessionId, Option<MacroUserIdStr<'static>>)>>,
+}
+impl AgentSessionNotificationRecipient for Controls {
+ async fn purge_owned_session(
+ &self,
+ _: AgentSessionId,
+ _: &Owner,
+ ) -> SessionResult<OwnedPurgeOutcome> {
+ unreachable!()
+ }
+ async fn delete_user_sessions(&self, _: MacroUserIdStr<'static>) -> SessionResult<()> {
+ unreachable!()
+ }
+ async fn session_deleted(&self, id: AgentSessionId) -> SessionResult<()> {
+ self.deleted.lock().unwrap().push(id);
+ Ok(())
+ }
+ async fn control_event(
+ &self,
+ id: AgentSessionId,
+ event: ControlEvent,
+ ) -> SessionResult<AcceptedControl> {
+ self.controls.lock().unwrap().push((id, event.actor));
+ Ok(AcceptedControl {
+ action_id: AgentActionId::mint(),
+ disposition: crate::domain::ports::ControlDisposition::Sent,
+ })
+ }
+ async fn queued_controls(&self, _: AgentSessionId) -> SessionResult<Vec<QueuedControl>> {
+ unreachable!()
+ }
+ async fn edit_queued_control(
+ &self,
+ _: AgentSessionId,
+ _: AgentActionId,
+ _: String,
+ _: Option<MacroUserIdStr<'static>>,
+ ) -> SessionResult<()> {
+ unreachable!()
+ }
+ async fn remove_queued_control(
+ &self,
+ _: AgentSessionId,
+ _: AgentActionId,
+ _: Option<MacroUserIdStr<'static>>,
+ ) -> SessionResult<()> {
+ unreachable!()
+ }
+ async fn steer_queued_control(
+ &self,
+ _: AgentSessionId,
+ _: AgentActionId,
+ _: Option<MacroUserIdStr<'static>>,
+ ) -> SessionResult<()> {
+ unreachable!()
+ }
+ async fn set_sandbox_size(&self, _: AgentSessionId, _: SandboxSize) -> SessionResult<()> {
+ unreachable!()
+ }
+ async fn session_harness(
+ &self,
+ _: AgentSessionId,
+ ) -> SessionResult<Option<harness_id::HarnessId>> {
+ unreachable!()
+ }
+}
+
+#[derive(Clone)]
+struct FakeEntityAccessService {
+ access_level: Option<AccessLevel>,
+}
+impl EntityAccessService for FakeEntityAccessService {
+ async fn generate_entity_access_receipt<T: RequiredPermission>(
+ &self,
+ _user_id: &MacroUserId<Lowercase<'_>>,
+ _user_org_id: Option<i64>,
+ _entity_id: &str,
+ _entity_type: EntityType,
+ ) -> Result<EntityAccessReceipt<T>, AccessError> {
+ panic!("unexpected generate_entity_access_receipt call")
+ }
+
+ async fn generate_bot_entity_access_receipt<T: RequiredPermission>(
+ &self,
+ bot_id: BotId,
+ scope: BotAccessScope,
+ entity_id: &str,
+ entity_type: EntityType,
+ ) -> Result<EntityAccessReceipt<T>, AccessError> {
+ let _ = (bot_id, scope, entity_id, entity_type);
+ unreachable!()
+ }
+
+ async fn get_access_level(
+ &self,
+ user_id: Option<&MacroUserId<Lowercase<'_>>>,
+ entity_id: &str,
+ entity_type: EntityType,
+ ) -> Result<Option<AccessLevel>, AccessError> {
+ assert_eq!(user_id.unwrap().as_ref(), OWNER);
+ assert_eq!(entity_id, AgentSessionId::TEST_A.to_string());
+ assert_eq!(entity_type, EntityType::AgentSession);
+ Ok(self.access_level)
+ }
+
+ async fn check_access(
+ &self,
+ _user_id: Option<&MacroUserId<Lowercase<'_>>>,
+ _entity_id: &str,
+ _entity_type: EntityType,
+ _required_level: AccessLevel,
+ ) -> Result<AccessLevel, AccessError> {
+ panic!("unexpected check_access call")
+ }
+
+ async fn check_public_access(
+ &self,
+ _entity_id: &str,
+ _entity_type: EntityType,
+ _required_level: AccessLevel,
+ ) -> Result<AccessLevel, AccessError> {
+ panic!("unexpected check_public_access call")
+ }
+
+ async fn get_entity_permission(
+ &self,
+ user_id: Option<&MacroUserId<Lowercase<'_>>>,
+ entity_id: &str,
+ entity_type: EntityType,
+ _user_org_id: Option<i64>,
+ ) -> Result<EntityPermission, AccessError> {
+ let access_level = self
+ .get_access_level(user_id, entity_id, entity_type)
+ .await?
+ .ok_or(AccessError::Unauthorized)?;
+ Ok(EntityPermission::AccessLevel { access_level })
+ }
+
+ async fn get_crm_entity_permission_with_team(
+ &self,
+ _user_id: Option<&MacroUserId<Lowercase<'_>>>,
+ _entity_id: &str,
+ _entity_type: EntityType,
+ ) -> Result<(EntityPermission, Uuid, TeamRole), AccessError> {
+ panic!("unexpected get_crm_entity_permission_with_team call")
+ }
+
+ async fn get_users_by_entity(
+ &self,
+ _entity_id: &str,
+ _entity_type: EntityType,
+ ) -> Result<Vec<MacroUserIdStr<'static>>, AccessError> {
+ panic!("unexpected get_users_by_entity call")
+ }
+
+ async fn get_call_channel(
+ &self,
+ _call_id: &Uuid,
+ ) -> Result<Option<CallChannelInfo>, AccessError> {
+ panic!("unexpected get_call_channel call")
+ }
+
+ async fn get_call_channel_by_channel_id(
+ &self,
+ _channel_id: &Uuid,
+ ) -> Result<Option<CallChannelInfo>, AccessError> {
+ panic!("unexpected get_call_channel_by_channel_id call")
+ }
+
+ async fn get_user_team(
+ &self,
+ _user_id: &MacroUserId<Lowercase<'_>>,
+ ) -> Result<Option<UserTeamInfo>, AccessError> {
+ panic!("unexpected get_user_team call")
+ }
+}
+
+async fn request(
+ controls: Arc<Controls>,
+ level: AccessLevel,
+ method: &str,
+ suffix: &str,
+ key: bool,
+ user: bool,
+ body: serde_json::Value,
+) -> StatusCode {
+ let auth = MacroAuthorizationServiceImpl::new(
+ FakeJwtValidator,
+ InternalAuthConfig {
+ api_key: "test-key".into(),
+ default_user_id: None,
+ },
+ SelfBotAuthorizer,
+ NoUserApiKeyAuthorizer,
+ );
+ let router = super::super::tool_actions::agent_session_tool_actions_router(
+ AgentSessionControlState::new(
+ controls,
+ Arc::new(FakeEntityAccessService {
+ access_level: Some(level),
+ }),
+ MacroAuthorizationState::new(Arc::new(auth)),
+ ),
+ );
+ let mut req = Request::builder()
+ .method(method)
+ .uri(format!(
+ "/internal/agent-sessions/{}{suffix}",
+ AgentSessionId::TEST_A
+ ))
+ .header("content-type", "application/json");
+ if key {
+ req = req.header(INTERNAL_API_KEY_HEADER, "test-key");
+ }
+ if user {
+ req = req.header(INTERNAL_MACRO_USER_ID_HEADER, OWNER);
+ }
+ router
+ .oneshot(req.body(Body::from(body.to_string())).unwrap())
+ .await
+ .unwrap()
+ .status()
+}
+
+#[tokio::test]
+async fn internal_actions_require_user_identity_and_sufficient_entity_access() {
+ let controls = Arc::new(Controls::default());
+ for (key, user) in [(false, false), (false, true), (true, false)] {
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::Owner,
+ "DELETE",
+ "",
+ key,
+ user,
+ serde_json::Value::Null
+ )
+ .await,
+ StatusCode::UNAUTHORIZED
+ );
+ }
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::Edit,
+ "DELETE",
+ "",
+ true,
+ true,
+ serde_json::Value::Null
+ )
+ .await,
+ StatusCode::UNAUTHORIZED
+ );
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::View,
+ "POST",
+ "/control",
+ true,
+ true,
+ serde_json::json!({"type":"stop"})
+ )
+ .await,
+ StatusCode::UNAUTHORIZED
+ );
+ assert!(controls.deleted.lock().unwrap().is_empty());
+ assert!(controls.controls.lock().unwrap().is_empty());
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::Owner,
+ "DELETE",
+ "",
+ true,
+ true,
+ serde_json::Value::Null
+ )
+ .await,
+ StatusCode::NO_CONTENT
+ );
+ assert_eq!(*controls.deleted.lock().unwrap(), [AgentSessionId::TEST_A]);
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::Edit,
+ "POST",
+ "/control",
+ true,
+ true,
+ serde_json::json!({"type":"prompt","prompt":"Continue"})
+ )
+ .await,
+ StatusCode::OK
+ );
+ assert_eq!(
+ *controls.controls.lock().unwrap(),
+ [(
+ AgentSessionId::TEST_A,
+ Some(MacroUserIdStr::try_from(OWNER.to_owned()).unwrap())
+ )]
+ );
+}
+
+#[tokio::test]
+async fn tools_cannot_approve_requests_or_supply_another_actor() {
+ let controls = Arc::new(Controls::default());
+ for body in [
+ serde_json::json!({"type":"respondToPermission"}),
+ serde_json::json!({"type":"respondElicitation"}),
+ serde_json::json!({"type":"prompt","prompt":"Hello","actor":STRANGER}),
+ ] {
+ assert_eq!(
+ request(
+ controls.clone(),
+ AccessLevel::Owner,
+ "POST",
+ "/control",
+ true,
+ true,
+ body
+ )
+ .await,
+ StatusCode::UNPROCESSABLE_ENTITY
+ );
+ }
+ assert!(controls.controls.lock().unwrap().is_empty());
+}
diff --git a/crates/agent_session/src/inbound/axum_router/tool_actions.rs b/crates/agent_session/src/inbound/axum_router/tool_actions.rs
new file mode 100644
index 0000000000..82e054a18a
--- /dev/null
+++ b/crates/agent_session/src/inbound/axum_router/tool_actions.rs
@@ -0,0 +1,79 @@
+//! Internal tool calls cannot impersonate a human approval or omit the acting user.
+use super::*;
+use crate::domain::tool_actions::SessionAction;
+use macro_authorization::{InternalOnly, UserOrInternal};
+
+/// Session controls for authenticated services acting for a verified user.
+pub fn agent_session_tool_actions_router<
+ R: AgentSessionNotificationRecipient,
+ Access: EntityAccessService,
+ Auth: MacroAuthorizationService,
+>(
+ state: AgentSessionControlState<R, Access, Auth>,
+) -> Router {
+ Router::new().nest(
+ "/internal/agent-sessions",
+ Router::new()
+ .route("/{session_id}", delete(delete_session::<R, Access, Auth>))
+ .route("/{session_id}/control", post(control::<R, Access, Auth>))
+ .with_state(state),
+ )
+}
+
+async fn delete_session<
+ R: AgentSessionNotificationRecipient,
+ Access: EntityAccessService,
+ Auth: MacroAuthorizationService,
+>(
+ _internal: MacroAuthorizationExtractor<Auth, InternalOnly>,
+ _user: MacroAuthorizationExtractor<Auth, UserOrInternal>,
+ _access: AgentSessionAccessLevelExtractor<OwnerAccessLevel, Access, Auth>,
+ State(state): State<AgentSessionControlState<R, Access, Auth>>,
+ Path(id): Path<Uuid>,
+) -> Result<StatusCode, AgentSessionApiError> {
+ state
+ .recipient
+ .session_deleted(AgentSessionId::new_from_uuid(id))
+ .await?;
+ Ok(StatusCode::NO_CONTENT)
+}
+
+async fn control<
+ R: AgentSessionNotificationRecipient,
+ Access: EntityAccessService,
+ Auth: MacroAuthorizationService,
+>(
+ _internal: MacroAuthorizationExtractor<Auth, InternalOnly>,
+ user: MacroAuthorizationExtractor<Auth, UserOrInternal>,
+ access: AgentSessionAccessLevelExtractor<EditAccessLevel, Access, Auth>,
+ State(state): State<AgentSessionControlState<R, Access, Auth>>,
+ Path(id): Path<Uuid>,
+ Json(action): Json<SessionAction>,
+) -> Result<Json<ControlResponse>, AgentSessionApiError> {
+ let action = match action {
+ SessionAction::Prompt { prompt } if !prompt.trim().is_empty() => {
+ AgentAction::prompt(prompt)
+ }
+ SessionAction::Stop => AgentAction::Stop,
+ _ => return Err(AgentSessionError::Forbidden.into()),
+ };
+ let accepted = state
+ .recipient
+ .control_event(
+ AgentSessionId::new_from_uuid(id),
+ ControlEvent::authorized(
+ action,
+ None,
+ None,
+ crate::domain::control::ControlPrincipal::Runtime(Some(
+ user.authorization.user.macro_user_id,
+ )),
+ access.entity_access_receipt,
+ )?,
+ )
+ .await?;
+ Ok(Json(ControlResponse {
+ action_id: accepted.action_id,
+ status: accepted.disposition.into(),
+ }))
+}
diff --git a/crates/agent_session/src/inbound/coding_agents.rs b/crates/agent_session/src/inbound/coding_agents.rs
index 829668d790..74a88ebe4f 100644
--- a/crates/agent_session/src/inbound/coding_agents.rs
+++ b/crates/agent_session/src/inbound/coding_agents.rs
@@ -65,6 +65,7 @@ pub fn coding_agents_router<Service: CodingAgentService, Auth: MacroAuthorizatio
Router::new()
.route("/list", post(list::<Service, Auth>))
.route("/dispatch", post(dispatch::<Service, Auth>))
+ .route("/create-session", post(create::<Service, Auth>))
.layer(DefaultBodyLimit::max(MAX_COMMAND_BYTES))
.layer(middleware::from_fn(bound_request))
.with_state(state),
@@ -113,7 +114,7 @@ impl IntoResponse for ApiError {
}
async fn bound_request(request: Request, next: Next) -> Response {
- let is_dispatch = request.uri().path().ends_with("/dispatch");
+ let is_dispatch = !request.uri().path().ends_with("/list");
let timeout = if is_dispatch {
DISPATCH_TIMEOUT
} else {
@@ -161,3 +162,11 @@ async fn dispatch<Service: CodingAgentService, Auth: MacroAuthorizationService>(
#[cfg(test)]
mod test;
+
+async fn create<Service: CodingAgentService, Auth: MacroAuthorizationService>(
+ State(state): State<CodingAgentsState<Service, Auth>>,
+ _internal: MacroAuthorizationExtractor<Auth, InternalOnly>,
+ command: Result<Json<DispatchCodingAgentRequest>, JsonRejection>,
+) -> Result<Json<DispatchedCodingAgent>, ApiError> {
+ Ok(Json(state.service.create(command?.0).await?))
+}
diff --git a/crates/agent_session/src/inbound/coding_agents/test.rs b/crates/agent_session/src/inbound/coding_agents/test.rs
index 79e7a796fb..98a7d2920f 100644
--- a/crates/agent_session/src/inbound/coding_agents/test.rs
+++ b/crates/agent_session/src/inbound/coding_agents/test.rs
@@ -35,6 +35,14 @@ struct ServiceSpy {
}
impl CodingAgentService for ServiceSpy {
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ self.dispatch(command)
+ }
+
fn list(
&self,
user_id: MacroUserIdStr<'static>,
@@ -107,7 +115,7 @@ async fn body(response: Response) -> Value {
#[tokio::test]
async fn internal_credentials_are_required_before_discovery_or_dispatch() {
let service = Arc::new(ServiceSpy::default());
- for operation in ["list", "dispatch"] {
+ for operation in ["list", "dispatch", "create-session"] {
for (header, expected) in [
(None, StatusCode::UNAUTHORIZED),
(
@@ -132,7 +140,7 @@ async fn internal_credentials_are_required_before_discovery_or_dispatch() {
#[tokio::test]
async fn authenticated_commands_preserve_user_and_task_identity() {
let service = Arc::new(ServiceSpy::default());
- for operation in ["list", "dispatch"] {
+ for operation in ["list", "dispatch", "create-session"] {
let command = command(operation);
let response = app(service.clone())
.oneshot(request(
@@ -157,7 +165,7 @@ async fn authenticated_commands_preserve_user_and_task_identity() {
#[tokio::test]
async fn malformed_identity_and_oversized_tasks_never_reach_the_domain() {
let service = Arc::new(ServiceSpy::default());
- for operation in ["list", "dispatch"] {
+ for operation in ["list", "dispatch", "create-session"] {
for invalid in [None, Some(json!("invalid-user")), Some(Value::Null)] {
let mut command = command(operation);
command.as_object_mut().unwrap().remove("user_id");
diff --git a/crates/agent_session/src/inbound/toolset/coding_agents.rs b/crates/agent_session/src/inbound/toolset/coding_agents.rs
index bef58105d3..63bf8a1d9e 100644
--- a/crates/agent_session/src/inbound/toolset/coding_agents.rs
+++ b/crates/agent_session/src/inbound/toolset/coding_agents.rs
@@ -24,6 +24,8 @@ mod test;
pub struct CodingAgentToolContext {
/// Discovery, authorization, and dispatch remain in the domain service.
pub service: Arc<dyn CodingAgentService>,
+ /// Existing-session actions through the owning harness service.
+ pub sessions: Arc<dyn crate::domain::tool_actions::SessionActions>,
}
/// Discover the user's available coding personas before selecting one.
@@ -121,6 +123,46 @@ fn tool_error(error: CodingAgentError) -> ToolCallError {
/// Discovery and delegation for non-coding agent hosts.
pub fn coding_agent_toolset() -> AsyncToolCollection<CodingAgentToolContext> {
AsyncToolCollection::new()
+ .add_tool::<super::manage_agent_session::ManageAgentSession, CodingAgentToolContext>()
+ .add_tool::<CreateAgentSession, CodingAgentToolContext>()
.add_tool::<ListCodingAgents, CodingAgentToolContext>()
.add_tool::<DispatchCodingAgent, CodingAgentToolContext>()
}
+
+/// Start a new conversation with an existing agent persona.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[schemars(
+ title = "CreateAgentSession",
+ description = "Start a new session with a coding or chat agent from ListAgents. Provide the agent botId and a self-contained initial prompt. The new session does not inherit this conversation. Returns its session ID after the first prompt is accepted, not completed work. Use ManageAgentSession to continue an existing session. Create once; do not automatically retry after an uncertain failure."
+)]
+pub struct CreateAgentSession {
+ /// Agent persona botId from ListAgents.
+ pub agent_id: Uuid,
+ /// Complete initial task and relevant context.
+ pub prompt: String,
+}
+impl ToolAnnotated for CreateAgentSession {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Create agent session").with_open_world();
+}
+#[async_trait]
+impl AsyncTool<CodingAgentToolContext> for CreateAgentSession {
+ type Output = DispatchedCodingAgent;
+ #[tracing::instrument(skip_all, err)]
+ async fn call(
+ &self,
+ context: ServiceContext<CodingAgentToolContext>,
+ request: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ context
+ .service
+ .create(DispatchCodingAgentRequest {
+ user_id: request.user_id,
+ agent_id: self.agent_id,
+ prompt: self.prompt.clone(),
+ })
+ .await
+ .map_err(tool_error)
+ }
+}
diff --git a/crates/agent_session/src/inbound/toolset/coding_agents/test.rs b/crates/agent_session/src/inbound/toolset/coding_agents/test.rs
index e654fdb85d..16ad723d8c 100644
--- a/crates/agent_session/src/inbound/toolset/coding_agents/test.rs
+++ b/crates/agent_session/src/inbound/toolset/coding_agents/test.rs
@@ -12,6 +12,14 @@ struct Service {
}
impl CodingAgentService for Service {
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ self.dispatch(command)
+ }
+
fn list(
&self,
user_id: MacroUserIdStr<'static>,
@@ -44,6 +52,7 @@ async fn tools_always_use_the_authenticated_request_identity() {
let service = Arc::new(Service::default());
let context = ServiceContext(CodingAgentToolContext {
service: service.clone(),
+ sessions: service.clone(),
});
let caller = MacroUserIdStr::try_from("macro|[email protected]".to_owned()).unwrap();
let request = RequestContext::new(caller.clone());
@@ -84,3 +93,24 @@ fn tools_reject_an_ai_supplied_user_identity() {
.is_err()
);
}
+
+impl crate::domain::tool_actions::SessionActions for Service {
+ fn execute(
+ &self,
+ _user: MacroUserIdStr<'static>,
+ _id: Uuid,
+ _action: crate::domain::tool_actions::SessionAction,
+ ) -> Pin<
+ Box<
+ dyn Future<
+ Output = Result<
+ crate::domain::tool_actions::SessionActionResult,
+ crate::domain::tool_actions::SessionActionError,
+ >,
+ > + Send
+ + '_,
+ >,
+ > {
+ Box::pin(async { panic!("this test must not invoke session management") })
+ }
+}
diff --git a/crates/agent_session/src/inbound/toolset/manage_agent_session.rs b/crates/agent_session/src/inbound/toolset/manage_agent_session.rs
new file mode 100644
index 0000000000..44d123b4fa
--- /dev/null
+++ b/crates/agent_session/src/inbound/toolset/manage_agent_session.rs
@@ -0,0 +1,47 @@
+//! Session workflow actions routed to the harness domain service.
+use super::CodingAgentToolContext;
+use crate::domain::tool_actions::{SessionAction, SessionActionResult};
+use ai_toolset::{
+ AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolCallError,
+ ToolResult,
+};
+use async_trait::async_trait;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use uuid::Uuid;
+
+/// Manage an existing agent conversation.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[schemars(
+ title = "ManageAgentSession",
+ description = "Rename, archive/unarchive, delete, prompt, or stop an agent session. Use ListEntities or NameSearch to find sessions and ReadAgentSession to inspect them. Rename, archive, and delete require ownership; prompting and stopping require edit access. Delete releases the runtime and permanently removes the session; use only when the user asks to delete it. Prompt returns sent/queued acceptance, not completed work. After an uncertain error, read the session before retrying; never automatically resend a prompt. This tool cannot answer permission or approval requests."
+)]
+pub struct ManageAgentSession {
+ /// Session UUID from a mention, listing, or search result.
+ pub session_id: Uuid,
+ /// The session action and its parameters.
+ pub action: SessionAction,
+}
+impl ToolAnnotated for ManageAgentSession {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Manage agent session");
+}
+#[async_trait]
+impl AsyncTool<CodingAgentToolContext> for ManageAgentSession {
+ type Output = SessionActionResult;
+ #[tracing::instrument(skip_all, fields(session_id = %self.session_id), err)]
+ async fn call(
+ &self,
+ context: ServiceContext<CodingAgentToolContext>,
+ request: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ context
+ .sessions
+ .execute(request.user_id, self.session_id, self.action.clone())
+ .await
+ .map_err(|error| ToolCallError {
+ description: error.to_string(),
+ internal_error: error.into(),
+ })
+ }
+}
diff --git a/crates/agent_session/src/inbound/toolset/mod.rs b/crates/agent_session/src/inbound/toolset/mod.rs
index 820ea5533e..f611651243 100644
--- a/crates/agent_session/src/inbound/toolset/mod.rs
+++ b/crates/agent_session/src/inbound/toolset/mod.rs
@@ -3,6 +3,7 @@
mod coding_agents;
mod context;
mod link_task;
+mod read_agent_session;
mod set_pull_request;
mod task_pull_requests;
@@ -12,5 +13,11 @@ pub use coding_agents::{
};
pub use context::SessionToolContext;
pub use link_task::LinkTask;
+pub use read_agent_session::{ReadAgentSession, ReadAgentSessionContext};
pub use set_pull_request::SetPullRequest;
pub use task_pull_requests::TaskPullRequestsTool;
+
+mod manage_agent_session;
+
+mod sharing;
+pub use sharing::{ReadAgentSessionSharing, UpdateAgentSessionSharing};
diff --git a/crates/agent_session/src/inbound/toolset/read_agent_session.rs b/crates/agent_session/src/inbound/toolset/read_agent_session.rs
new file mode 100644
index 0000000000..2b57359f97
--- /dev/null
+++ b/crates/agent_session/src/inbound/toolset/read_agent_session.rs
@@ -0,0 +1,87 @@
+//! Read a session using the authenticated caller's view access.
+
+use std::sync::Arc;
+
+use ai_toolset::{
+ AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolCallError,
+ ToolResult,
+};
+use async_trait::async_trait;
+use entity_access::domain::{
+ models::{EntityType, ViewAccessLevel},
+ ports::EntityAccessService,
+};
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+use crate::domain::{
+ ports::{AgentSessionLogRepo, AgentSessionRepo},
+ read::{SessionConversation, SessionReader},
+};
+
+/// Session reads and the shared access boundary.
+#[derive(Clone)]
+pub struct ReadAgentSessionContext<R, A> {
+ /// Domain conversation reader.
+ pub service: Arc<SessionReader<R>>,
+ /// Existing session-sharing policy.
+ pub sharing: Arc<crate::domain::sharing::SessionSharingService<R>>,
+ /// Mints a view-access capability for the caller.
+ pub access: Arc<A>,
+}
+
+/// Read prompts, replies, tool activity, and failures in an agent session.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[schemars(
+ title = "ReadAgentSession",
+ description = "Read an agent session by its ID from an agent-session mention or search result. Returns the latest 20 messages in chronological order, including prompts, replies, tool activity and errors. Optionally select a turn number to inspect earlier history. Each message is capped at 4000 characters; truncated flags identify omitted history or text. Requires view access to the session."
+)]
+pub struct ReadAgentSession {
+ /// Session to read.
+ #[schemars(description = "The agent session UUID from its mention or search result.")]
+ pub session_id: uuid::Uuid,
+ /// Optional turn filter.
+ #[schemars(
+ description = "Read only this turn number, as returned in messages; omit for recent history."
+ )]
+ pub turn: Option<u32>,
+}
+
+impl ToolAnnotated for ReadAgentSession {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read agent session");
+}
+
+#[async_trait]
+impl<R, A> AsyncTool<ReadAgentSessionContext<R, A>> for ReadAgentSession
+where
+ R: AgentSessionRepo + AgentSessionLogRepo + Clone + 'static,
+ A: EntityAccessService,
+{
+ type Output = SessionConversation;
+
+ #[tracing::instrument(name = "agent_session.tool.read", skip_all, fields(session_id = %self.session_id), err)]
+ async fn call(
+ &self,
+ context: ServiceContext<ReadAgentSessionContext<R, A>>,
+ request: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ let access = context.access.generate_entity_access_receipt::<ViewAccessLevel>(
+ &request.user_id, None, &self.session_id.to_string(), EntityType::AgentSession,
+ ).await.map_err(|error| ToolCallError {
+ description: "Unable to read this agent session. Check the session ID and that it is shared with you.".into(),
+ internal_error: error.into(),
+ })?;
+ context
+ .service
+ .read(access, self.turn)
+ .await
+ .map_err(|error| ToolCallError {
+ description: "Unable to load the agent session conversation.".into(),
+ internal_error: error.into(),
+ })
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/agent_session/src/inbound/toolset/read_agent_session/test.rs b/crates/agent_session/src/inbound/toolset/read_agent_session/test.rs
new file mode 100644
index 0000000000..c842301725
--- /dev/null
+++ b/crates/agent_session/src/inbound/toolset/read_agent_session/test.rs
@@ -0,0 +1,38 @@
+use super::*;
+use crate::testing::InMemoryAgentSessionRepo;
+use entity_access::domain::ports::NoOpEntityAccessService;
+use macro_user_id::user_id::MacroUserIdStr;
+
+#[tokio::test]
+async fn failed_access_check_never_reads_session_metadata_or_history() {
+ let repo = InMemoryAgentSessionRepo::new();
+ let context = ServiceContext(ReadAgentSessionContext {
+ service: Arc::new(SessionReader::new(repo.clone())),
+ sharing: Arc::new(crate::domain::sharing::SessionSharingService::new(
+ repo.clone(),
+ )),
+ access: Arc::new(NoOpEntityAccessService),
+ });
+ let result = ReadAgentSession {
+ session_id: uuid::Uuid::nil(),
+ turn: None,
+ }
+ .call(
+ context,
+ RequestContext::new(MacroUserIdStr::try_from_email("[email protected]").expect("viewer")),
+ )
+ .await;
+ assert!(result.is_err());
+ assert_eq!(repo.session_reads(), 0);
+ assert_eq!(repo.log_reads(), 0);
+}
+
+#[test]
+fn rejects_ai_supplied_identity() {
+ assert!(
+ serde_json::from_value::<ReadAgentSession>(serde_json::json!({
+ "sessionId": uuid::Uuid::nil(), "userId": "macro|[email protected]"
+ }))
+ .is_err()
+ );
+}
diff --git a/crates/agent_session/src/inbound/toolset/sharing.rs b/crates/agent_session/src/inbound/toolset/sharing.rs
new file mode 100644
index 0000000000..21615ad4de
--- /dev/null
+++ b/crates/agent_session/src/inbound/toolset/sharing.rs
@@ -0,0 +1,288 @@
+//! Session sharing tools use the same domain policy as the app.
+use super::ReadAgentSessionContext;
+use crate::domain::sharing::{SessionSharing, SessionSharingRepo};
+use ai_toolset::{
+ AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolCallError,
+ ToolResult,
+};
+use async_trait::async_trait;
+use entity_access::domain::{
+ models::{EntityType, OwnerAccessLevel, ViewAccessLevel},
+ ports::EntityAccessService,
+};
+use models_permissions::share_permission::{
+ LinkShare, UpdateSharePermissionRequestV2,
+ access_level::AccessLevel,
+ channel_share_permission::{UpdateChannelSharePermission, UpdateOperation},
+};
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+/// A share can be disabled or grant a non-owner permission.
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, JsonSchema, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SessionShareAccess {
+ /// Disable this share.
+ Off,
+ /// View only.
+ View,
+ /// View and comment.
+ Comment,
+ /// Edit.
+ Edit,
+}
+
+impl SessionShareAccess {
+ fn level(self) -> Option<AccessLevel> {
+ match self {
+ Self::Off => None,
+ Self::View => Some(AccessLevel::View),
+ Self::Comment => Some(AccessLevel::Comment),
+ Self::Edit => Some(AccessLevel::Edit),
+ }
+ }
+}
+
+/// Who an item's share link admits.
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, JsonSchema, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SessionLinkScope {
+ /// Disable link sharing.
+ Off,
+ /// Anyone with the link.
+ Public,
+ /// Members of the owner's team with the link.
+ Team,
+}
+
+/// One channel's grant to set or remove.
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionSharingChannel {
+ /// Channel id to share with or revoke.
+ #[schemars(description = "Channel id to share with or revoke.")]
+ pub channel_id: Uuid,
+ /// Desired grant; off removes only this channel's grant.
+ #[schemars(description = "Desired grant; off removes only this channel's grant.")]
+ pub access: SessionShareAccess,
+}
+
+/// A channel's existing session access.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionChannelGrant {
+ /// Channel identity.
+ pub channel_id: String,
+ /// Effective access granted through this share.
+ pub access: AccessLevel,
+}
+
+/// Authoritative sharing settings after a read or mutation.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionSharingResponse {
+ /// Session owner's principal.
+ pub owner: String,
+ /// Who the link admits, or off when disabled.
+ pub link_scope: SessionLinkScope,
+ /// Access through the enabled link.
+ pub link_access: Option<AccessLevel>,
+ /// Explicit access for the owner's team.
+ pub team_access: Option<AccessLevel>,
+ /// Explicit channel grants.
+ pub channels: Vec<SessionChannelGrant>,
+}
+impl From<models_permissions::share_permission::SharePermissionV2> for SessionSharingResponse {
+ fn from(value: models_permissions::share_permission::SharePermissionV2) -> Self {
+ Self {
+ owner: value.owner,
+ link_scope: match value.link_share {
+ None => SessionLinkScope::Off,
+ Some(LinkShare::Public) => SessionLinkScope::Public,
+ Some(LinkShare::Team) => SessionLinkScope::Team,
+ },
+ link_access: value.link_share_access_level,
+ team_access: value.team_share_access_level,
+ channels: value
+ .channel_share_permissions
+ .unwrap_or_default()
+ .into_iter()
+ .map(|grant| SessionChannelGrant {
+ channel_id: grant.channel_id,
+ access: grant.access_level,
+ })
+ .collect(),
+ }
+ }
+}
+
+/// Read the current link, team, and channel grants.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[schemars(
+ title = "ReadAgentSessionSharing",
+ description = "Read an agent session's current owner, link sharing, team access, and channel grants. Requires view access. Use UpdateAgentSessionSharing to change grants as the owner."
+)]
+pub struct ReadAgentSessionSharing {
+ /// Session UUID.
+ pub session_id: Uuid,
+}
+impl ToolAnnotated for ReadAgentSessionSharing {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read session sharing");
+}
+
+/// Change only the named sharing settings.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[schemars(
+ title = "UpdateAgentSessionSharing",
+ description = "Change an agent session's link, team, or channel sharing as its owner. Omitted settings remain unchanged; off revokes that grant. Requires an explicit user request to change sharing. Private persona conversations cannot be shared. Returns the resulting settings."
+)]
+pub struct UpdateAgentSessionSharing {
+ /// Session UUID.
+ pub session_id: Uuid,
+
+ /// Who the share link admits.
+ #[schemars(
+ description = "Who the item's share link admits: public (anyone with the link), team (the owner's team members with the link), or off to disable link sharing."
+ )]
+ #[serde(default)]
+ pub link_scope: Option<SessionLinkScope>,
+ /// Permission granted by an enabled link.
+ #[schemars(
+ description = "Permission granted by an enabled share link. Off resets it to the default level."
+ )]
+ #[serde(default)]
+ pub link_access: Option<SessionShareAccess>,
+ /// Explicit owner-team grant.
+ #[schemars(description = "Access for everyone on the owner's team; off removes it.")]
+ #[serde(default)]
+ pub team_access: Option<SessionShareAccess>,
+ /// Channel grants to set or remove.
+ #[schemars(
+ description = "Individual channel grants to set or remove; other channel grants stay unchanged."
+ )]
+ #[serde(default)]
+ pub channels: Option<Vec<SessionSharingChannel>>,
+}
+impl UpdateAgentSessionSharing {
+ pub(super) fn policy(&self) -> UpdateSharePermissionRequestV2 {
+ UpdateSharePermissionRequestV2 {
+ link_share: self.link_scope.map(|scope| match scope {
+ SessionLinkScope::Off => None,
+ SessionLinkScope::Public => Some(LinkShare::Public),
+ SessionLinkScope::Team => Some(LinkShare::Team),
+ }),
+ link_share_access_level: self.link_access.map(SessionShareAccess::level),
+ team_share_access_level: self.team_access.map(SessionShareAccess::level),
+ channel_share_permissions: self.channels.as_ref().map(|channels| {
+ channels
+ .iter()
+ .map(|channel| UpdateChannelSharePermission {
+ operation: if channel.access == SessionShareAccess::Off {
+ UpdateOperation::Remove
+ } else {
+ UpdateOperation::Replace
+ },
+ channel_id: channel.channel_id.to_string(),
+ access_level: channel.access.level(),
+ })
+ .collect()
+ }),
+ }
+ }
+
+ pub(super) fn is_empty(&self) -> bool {
+ self.link_scope.is_none()
+ && self.link_access.is_none()
+ && self.team_access.is_none()
+ && self.channels.as_ref().is_none_or(Vec::is_empty)
+ }
+}
+
+impl ToolAnnotated for UpdateAgentSessionSharing {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Update session sharing").with_idempotent();
+}
+
+#[async_trait]
+impl<R, A> AsyncTool<ReadAgentSessionContext<R, A>> for ReadAgentSessionSharing
+where
+ R: SessionSharingRepo + Clone + 'static,
+ A: EntityAccessService,
+{
+ type Output = SessionSharingResponse;
+ #[tracing::instrument(skip_all, fields(session_id = %self.session_id), err)]
+ async fn call(
+ &self,
+ context: ServiceContext<ReadAgentSessionContext<R, A>>,
+ request: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ let access = context
+ .access
+ .generate_entity_access_receipt::<ViewAccessLevel>(
+ &request.user_id,
+ None,
+ &self.session_id.to_string(),
+ EntityType::AgentSession,
+ )
+ .await
+ .map_err(|e| ToolCallError {
+ description: "Unable to read session sharing.".into(),
+ internal_error: e.into(),
+ })?;
+ let result = context
+ .sharing
+ .permissions(&access)
+ .await
+ .map_err(|e| ToolCallError {
+ description: e.to_string(),
+ internal_error: e.into(),
+ })?;
+ Ok(result.into())
+ }
+}
+#[async_trait]
+impl<R, A> AsyncTool<ReadAgentSessionContext<R, A>> for UpdateAgentSessionSharing
+where
+ R: SessionSharingRepo + Clone + 'static,
+ A: EntityAccessService,
+{
+ type Output = SessionSharingResponse;
+ #[tracing::instrument(skip_all, fields(session_id = %self.session_id), err)]
+ async fn call(
+ &self,
+ context: ServiceContext<ReadAgentSessionContext<R, A>>,
+ request: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ if self.is_empty() {
+ return Err(ToolCallError {
+ description: "Provide at least one sharing change.".into(),
+ internal_error: anyhow::anyhow!("empty sharing update"),
+ });
+ }
+ let access = context
+ .access
+ .generate_entity_access_receipt::<OwnerAccessLevel>(
+ &request.user_id,
+ None,
+ &self.session_id.to_string(),
+ EntityType::AgentSession,
+ )
+ .await
+ .map_err(|e| ToolCallError {
+ description: "You must own this session to change sharing.".into(),
+ internal_error: e.into(),
+ })?;
+ let result = context
+ .sharing
+ .update_permissions(&access, self.policy())
+ .await
+ .map_err(|e| ToolCallError {
+ description: e.to_string(),
+ internal_error: e.into(),
+ })?;
+ Ok(result.into())
+ }
+}
diff --git a/crates/agent_session/src/outbound/coding_agents_client.rs b/crates/agent_session/src/outbound/coding_agents_client.rs
index dbe7d9b58a..ea07d34f91 100644
--- a/crates/agent_session/src/outbound/coding_agents_client.rs
+++ b/crates/agent_session/src/outbound/coding_agents_client.rs
@@ -17,16 +17,18 @@ const LIST_TIMEOUT: Duration = Duration::from_secs(10);
const CONNECT_TIMEOUT: Duration = Duration::from_secs(3);
const MAX_RESPONSE_BYTES: usize = 1024 * 1024;
-#[derive(Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Operation {
List,
Dispatch,
+ Create,
}
impl Operation {
fn path(self) -> &'static str {
match self {
Self::List => "internal/coding-agents/list",
+ Self::Create => "internal/coding-agents/create-session",
Self::Dispatch => "internal/coding-agents/dispatch",
}
}
@@ -34,14 +36,14 @@ impl Operation {
fn timeout(self) -> Duration {
match self {
Self::List => LIST_TIMEOUT,
- Self::Dispatch => DISPATCH_TIMEOUT,
+ Self::Dispatch | Self::Create => DISPATCH_TIMEOUT,
}
}
fn uncertain_error(self) -> CodingAgentError {
match self {
Self::List => CodingAgentError::OperationFailed,
- Self::Dispatch => CodingAgentError::DispatchDeliveryUnknown,
+ Self::Dispatch | Self::Create => CodingAgentError::DispatchDeliveryUnknown,
}
}
}
@@ -49,9 +51,9 @@ impl Operation {
/// Internal service client that never redirects credentials or retries dispatch.
#[derive(Clone)]
pub struct CodingAgentsClient {
- client: Client,
- base_url: Url,
- internal_key: HeaderValue,
+ pub(super) client: Client,
+ pub(super) base_url: Url,
+ pub(super) internal_key: HeaderValue,
}
impl CodingAgentsClient {
@@ -85,6 +87,7 @@ impl CodingAgentsClient {
})
}
+ #[tracing::instrument(name = "agent_session.command", skip_all, fields(operation = ?operation), err)]
async fn command<T: DeserializeOwned>(
&self,
operation: Operation,
@@ -94,9 +97,12 @@ impl CodingAgentsClient {
.base_url
.join(operation.path())
.map_err(|_| CodingAgentError::OperationFailed)?;
+ let mut headers = reqwest::header::HeaderMap::new();
+ macro_tower_layers::inject_trace_headers(&mut headers);
let response = self
.client
.post(url)
+ .headers(headers)
.header(INTERNAL_API_KEY_HEADER, self.internal_key.clone())
.timeout(operation.timeout())
.json(command)
@@ -124,8 +130,7 @@ impl CodingAgentsClient {
CodingAgentError::DispatchFailed { .. } => status == StatusCode::BAD_GATEWAY,
CodingAgentError::DispatchDeliveryUnknown => {
status == StatusCode::BAD_GATEWAY
- || (operation == Operation::Dispatch
- && status == StatusCode::GATEWAY_TIMEOUT)
+ || (operation != Operation::List && status == StatusCode::GATEWAY_TIMEOUT)
}
};
// A contradictory envelope is not evidence that dispatch was refused.
@@ -172,6 +177,14 @@ async fn bounded_body(mut response: Response) -> Result<Vec<u8>, CodingAgentErro
}
impl CodingAgentService for CodingAgentsClient {
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ Box::pin(async move { self.command(Operation::Create, &command).await })
+ }
+
fn list(
&self,
user_id: MacroUserIdStr<'static>,
diff --git a/crates/agent_session/src/outbound/coding_agents_client/test.rs b/crates/agent_session/src/outbound/coding_agents_client/test.rs
index 06e823f62c..a175513607 100644
--- a/crates/agent_session/src/outbound/coding_agents_client/test.rs
+++ b/crates/agent_session/src/outbound/coding_agents_client/test.rs
@@ -323,3 +323,54 @@ fn configuration_rejects_invalid_urls_and_marks_credentials_sensitive() {
let client = CodingAgentsClient::new("https://example.com/agent-harness", KEY).unwrap();
assert!(client.internal_key.is_sensitive());
}
+
+#[tokio::test]
+async fn session_actions_send_the_verified_user_once_and_keep_uncertain_failures_safe() {
+ use crate::domain::tool_actions::{SessionAction, SessionActionError, SessionActions};
+ let id = Uuid::now_v7();
+ let action_id = Uuid::now_v7();
+ let server = server(vec![
+ Reply::json(200, json!({"actionId":action_id,"status":"queued"})),
+ Reply::json(502, json!({"secret":"provider output"})),
+ ])
+ .await;
+ let client = CodingAgentsClient::new(&format!("{}/agent-harness", server.url), KEY).unwrap();
+ let result = client
+ .execute(
+ MacroUserIdStr::try_from(USER).unwrap(),
+ id,
+ SessionAction::Prompt {
+ prompt: "Continue".into(),
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(result.action_id, Some(action_id));
+ assert!(matches!(
+ result.status,
+ Some(crate::domain::tool_actions::SessionControlStatus::Queued)
+ ));
+ assert!(matches!(
+ client
+ .execute(
+ MacroUserIdStr::try_from(USER).unwrap(),
+ id,
+ SessionAction::Stop
+ )
+ .await,
+ Err(SessionActionError::Unconfirmed)
+ ));
+ let requests = server.requests.lock().unwrap();
+ assert_eq!(requests.len(), 2);
+ assert!(requests[0].head.contains(&format!(
+ "POST /agent-harness/internal/agent-sessions/{id}/control"
+ )));
+ assert!(requests[0].head.to_lowercase().contains(&format!(
+ "{}: {USER}",
+ macro_authorization::INTERNAL_MACRO_USER_ID_HEADER
+ )));
+ assert_eq!(
+ requests[0].body,
+ json!({"type":"prompt","prompt":"Continue"})
+ );
+}
diff --git a/crates/agent_session/src/outbound/mod.rs b/crates/agent_session/src/outbound/mod.rs
index c7033f8b55..87d8974f07 100644
--- a/crates/agent_session/src/outbound/mod.rs
+++ b/crates/agent_session/src/outbound/mod.rs
@@ -13,3 +13,6 @@ pub mod connection_gateway_realtime;
/// Publishing lifecycle facts to the event broker.
pub mod broker_lifecycle_publisher;
+
+/// Session actions through the owning harness service.
+mod session_actions_client;
diff --git a/crates/agent_session/src/outbound/session_actions_client.rs b/crates/agent_session/src/outbound/session_actions_client.rs
new file mode 100644
index 0000000000..a3d3ab5c0c
--- /dev/null
+++ b/crates/agent_session/src/outbound/session_actions_client.rs
@@ -0,0 +1,131 @@
+//! Reuse session HTTP routes with internal credentials and a mandatory acting user.
+use super::coding_agents_client::CodingAgentsClient;
+use crate::domain::tool_actions::{
+ SessionAction, SessionActionError, SessionActionResult, SessionActions, SessionControlStatus,
+};
+use macro_authorization::{INTERNAL_API_KEY_HEADER, INTERNAL_MACRO_USER_ID_HEADER};
+use macro_user_id::user_id::MacroUserIdStr;
+use reqwest::{Method, StatusCode};
+use serde::Deserialize;
+use serde_json::json;
+use std::{pin::Pin, time::Duration};
+use tracing::Instrument;
+use uuid::Uuid;
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ControlReceipt {
+ action_id: Uuid,
+ status: SessionControlStatus,
+}
+
+impl SessionActions for CodingAgentsClient {
+ fn execute(
+ &self,
+ user: MacroUserIdStr<'static>,
+ session_id: Uuid,
+ action: SessionAction,
+ ) -> Pin<Box<dyn Future<Output = Result<SessionActionResult, SessionActionError>> + Send + '_>>
+ {
+ Box::pin(
+ async move {
+ let root = format!("agent-sessions/{session_id}");
+ let internal = format!("internal/agent-sessions/{session_id}");
+ let (method, path, body, message, control) = match action {
+ SessionAction::Rename { name } => (
+ Method::PUT,
+ format!("{root}/name"),
+ json!({"name":name}),
+ "Session renamed.",
+ false,
+ ),
+ SessionAction::Archive { archived } => (
+ Method::PUT,
+ format!("{root}/archived"),
+ json!({"isArchived":archived}),
+ if archived {
+ "Session archived."
+ } else {
+ "Session unarchived."
+ },
+ false,
+ ),
+ SessionAction::Delete => (
+ Method::DELETE,
+ internal,
+ json!(null),
+ "Session deleted.",
+ false,
+ ),
+ SessionAction::Prompt { prompt } => (
+ Method::POST,
+ format!("{internal}/control"),
+ json!({"type":"prompt", "prompt":prompt}),
+ "Prompt accepted.",
+ true,
+ ),
+ SessionAction::Stop => (
+ Method::POST,
+ format!("{internal}/control"),
+ json!({"type":"stop"}),
+ "Stop accepted.",
+ true,
+ ),
+ };
+ let url = self
+ .base_url
+ .join(&path)
+ .map_err(|_| SessionActionError::Unconfirmed)?;
+ let mut headers = reqwest::header::HeaderMap::new();
+ macro_tower_layers::inject_trace_headers(&mut headers);
+ let mut response = self
+ .client
+ .request(method, url)
+ .headers(headers)
+ .header(INTERNAL_API_KEY_HEADER, self.internal_key.clone())
+ .header(INTERNAL_MACRO_USER_ID_HEADER, user.as_ref())
+ .timeout(Duration::from_secs(30))
+ .json(&body)
+ .send()
+ .await
+ .map_err(|_| SessionActionError::Unconfirmed)?;
+ match response.status() {
+ StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN | StatusCode::NOT_FOUND => {
+ return Err(SessionActionError::Forbidden);
+ }
+ StatusCode::BAD_REQUEST
+ | StatusCode::UNPROCESSABLE_ENTITY
+ | StatusCode::CONFLICT => return Err(SessionActionError::Rejected),
+ status if !status.is_success() => return Err(SessionActionError::Unconfirmed),
+ _ => {}
+ }
+ let receipt = if control {
+ let mut bytes = Vec::new();
+ while let Some(chunk) = response
+ .chunk()
+ .await
+ .map_err(|_| SessionActionError::Unconfirmed)?
+ {
+ if bytes.len() + chunk.len() > 16_384 {
+ return Err(SessionActionError::Unconfirmed);
+ }
+ bytes.extend_from_slice(&chunk);
+ }
+ Some(
+ serde_json::from_slice::<ControlReceipt>(&bytes)
+ .map_err(|_| SessionActionError::Unconfirmed)?,
+ )
+ } else {
+ None
+ };
+ Ok(SessionActionResult {
+ session_id,
+ message: message.into(),
+ action_id: receipt.as_ref().map(|r| r.action_id),
+ status: receipt.map(|r| r.status),
+ })
+ }
+ .instrument(tracing::info_span!("agent_session.tool_action", session_id = %session_id)),
+ )
+ }
+}
diff --git a/crates/ai_tools/AGENTS.md b/crates/ai_tools/AGENTS.md
index 278137c0d2..b11680a95b 100644
--- a/crates/ai_tools/AGENTS.md
+++ b/crates/ai_tools/AGENTS.md
@@ -12,6 +12,8 @@ execution, display) that don't belong to a single domain.
- `src/lib.rs`: the composition point — imports each domain crate's
`inbound::toolset` module and builds the combined `AsyncToolCollection`
and frontend schema set.
+- `ReadAgentSession` is eager across chat, agent sessions, and MCP, and is also
+ available to subagents; keep its registration covered by the host tests.
- `src/subagent.rs`: dispatches `snippet_specs` to parallel subagents.
- `src/search.rs` / `src/search_tools.rs`: cross-entity search tools.
- `src/deferred.rs`: tools whose result arrives after the turn (long-running
@@ -45,6 +47,10 @@ execution, display) that don't belong to a single domain.
- Add a cross-domain tool: new module in `src/` → register in
`src/lib.rs`'s toolset assembly → regenerate schemas (see Checks).
+## Tool contracts
+
+- Executable toolsets exclude legacy chats in every host and code mode. Keep historical parsing compatibility only in `frontend_compat.rs`; never merge it into provider schemas.
+
## Checks
- `cargo test -p ai_tools` (`SQLX_OFFLINE` unset).
diff --git a/crates/ai_tools/Cargo.toml b/crates/ai_tools/Cargo.toml
index 4aeb964313..bf291d7412 100644
--- a/crates/ai_tools/Cargo.toml
+++ b/crates/ai_tools/Cargo.toml
@@ -8,6 +8,7 @@ version = "0.1.0"
test-support = []
[dependencies]
+clap = { workspace = true, features = ["derive"] }
favorites = { path = "../favorites", features = ["ai_tools", "postgres"] }
forms = { path = "../forms", features = ["ai_tools", "gateway", "postgres", "scheduling"] }
routines = { path = "../routines" }
diff --git a/crates/ai_tools/src/bin/gen_tool_schemas.rs b/crates/ai_tools/src/bin/gen_tool_schemas.rs
index b918017937..a1c203068a 100644
--- a/crates/ai_tools/src/bin/gen_tool_schemas.rs
+++ b/crates/ai_tools/src/bin/gen_tool_schemas.rs
@@ -1,9 +1,30 @@
-//! Binary to generate combined tool schemas JSON file.
+//! Generate frontend transcript schemas or the current public MCP registry.
+
+use clap::Parser;
+
+#[derive(Parser)]
+struct Args {
+ /// Export the executable public MCP registry instead of transcript schemas.
+ #[arg(long)]
+ mcp: bool,
+}
fn main() {
- let schemas = ai_tools::all_tool_frontend_schemas();
+ let public_mcp = Args::parse().mcp;
+ let schemas = if public_mcp {
+ ai_toolset::schema::frontend_schemas_builder()
+ .merge(&ai_tools::tools_for(ai_tools::AiHost::Mcp))
+ .build()
+ } else {
+ ai_tools::all_tool_frontend_schemas()
+ };
let json = schemas.to_json_pretty().expect("serialize schemas");
- std::fs::create_dir("schemas").expect("create schemas dir");
- std::fs::write("schemas/tools.json", &json).expect("write tools.json");
- println!("Generated ai_tools/schemas/tools.json");
+ std::fs::create_dir_all("schemas").expect("create schemas dir");
+ let output = if public_mcp {
+ "schemas/mcp-tools.json"
+ } else {
+ "schemas/tools.json"
+ };
+ std::fs::write(output, &json).expect("write tool schemas");
+ println!("Generated {output}");
}
diff --git a/crates/ai_tools/src/build_context.rs b/crates/ai_tools/src/build_context.rs
index 13049ff4e8..e35a689a87 100644
--- a/crates/ai_tools/src/build_context.rs
+++ b/crates/ai_tools/src/build_context.rs
@@ -490,7 +490,6 @@ pub async fn build_tool_service_context_from_env(
macro_event_broker.clone(),
entity_access_service.clone(),
document_tool_context.service.clone(),
- chat_tool_context.service.clone(),
user_email_service.clone(),
);
@@ -665,6 +664,10 @@ pub async fn build_tool_service_context_from_env(
document_storage_service_url,
pipedream_client,
),
+ read_agent_session_context: crate::build_read_agent_session_context(
+ pool.clone(),
+ entity_access_service.clone(),
+ ),
coding_agent_tool_context: crate::build_coding_agent_tool_context(
macro_service_urls::AgentHarnessServiceUrl::new()?,
env.internal_api_key.to_string(),
diff --git a/crates/ai_tools/src/frontend_compat.rs b/crates/ai_tools/src/frontend_compat.rs
new file mode 100644
index 0000000000..b9cd3a9bd3
--- /dev/null
+++ b/crates/ai_tools/src/frontend_compat.rs
@@ -0,0 +1,64 @@
+//! Historical transcript schemas. Never merge this into executable toolsets.
+use ai_toolset::schema::{FrontendToolEntry, ToolSchemaGenerator};
+use schemars::{JsonSchema, SchemaGenerator};
+use serde_json::json;
+
+pub(super) struct LegacyConversationSchemas;
+
+impl ToolSchemaGenerator for LegacyConversationSchemas {
+ fn register_schemas(&self, generator: &mut SchemaGenerator) -> Vec<FrontendToolEntry> {
+ // Search output shapes are unchanged except that live tools filter out chats.
+ // Retain the old union for saved responses, including its linked definitions.
+ let search = models_search::unified::UnifiedSearchResponseItem::json_schema(generator);
+ generator
+ .definitions_mut()
+ .insert("SessionAwareSearchResult".into(), search.into());
+ let definitions = generator.definitions_mut();
+ for (name, value) in [
+ ("SearchEntityType", "chats"),
+ ("ItemType", "ai_chat"),
+ ("ProjectItemType", "chat"),
+ ("RenameableEntityType", "chat"),
+ ("MoveableEntityType", "chat"),
+ ("TrashableEntityType", "chat"),
+ ("DuplicableEntityType", "chat"),
+ ("SharingEntityType", "chat"),
+ ("FavoritableEntityType", "chat"),
+ ("ToolEntityType", "chat"),
+ ("ToolPropertyTargetEntityType", "chat"),
+ ("ChannelShareEntityType", "chat"),
+ ("NotificationEntityType", "chat"),
+ ("ToolNotificationCategory", "chat"),
+ ] {
+ let schema = definitions
+ .get_mut(name)
+ .expect("historical tool type exists");
+ if let Some(values) = schema.get_mut("enum").and_then(|v| v.as_array_mut()) {
+ values.push(json!(value));
+ } else {
+ schema
+ .get_mut("oneOf")
+ .and_then(|v| v.as_array_mut())
+ .expect("historical entity enum")
+ .push(json!({"type":"string", "const":value}));
+ }
+ }
+ definitions
+ .get_mut("EntityItem")
+ .expect("listing output")
+ .get_mut("oneOf")
+ .and_then(|v| v.as_array_mut())
+ .expect("listing union")
+ .push(json!({
+ "type":"object",
+ "properties": {
+ "type":{"type":"string","const":"aiChat"},
+ "id":{"type":"string","format":"uuid"},
+ "name":{"type":"string"},
+ "tags":{"type":"array","items":{"$ref":"#/$defs/AppliedTag"},"default":[]}
+ },
+ "required":["type","id","name"]
+ }));
+ Vec::new()
+ }
+}
diff --git a/crates/ai_tools/src/lib.rs b/crates/ai_tools/src/lib.rs
index b42bf4fb51..8cae86e033 100644
--- a/crates/ai_tools/src/lib.rs
+++ b/crates/ai_tools/src/lib.rs
@@ -1,8 +1,10 @@
#![recursion_limit = "256"]
use activity::inbound::toolset::activity_toolset;
-use agent_session::inbound::toolset::coding_agent_toolset;
+use agent_session::inbound::toolset::{ReadAgentSession, coding_agent_toolset};
use ai_toolset::AsyncToolCollection;
+mod frontend_compat;
+
use ai_toolset::schema::{FrontendSchemas, ToolSchemaGenerator, frontend_schemas_builder};
#[cfg(test)]
@@ -35,7 +37,6 @@ use calendar_scheduling::inbound::toolset::{
};
use call::inbound::toolset::call_toolset;
use channels::inbound::toolset::channel_toolset;
-use chat::inbound::toolset::chat_toolset;
use cognition::inbound::toolset::cognition_toolset;
use crm::inbound::toolset::{crm_toolset, pipelines::pipeline_toolset};
use databases::inbound::toolset::{databases_read_only_toolset, databases_toolset};
@@ -88,23 +89,24 @@ pub use tool_context::{
ToolItemNotificationPreferenceToolContext, ToolMcpSelector, ToolNotificationQueue,
ToolNotificationService, ToolNotificationToolContext, ToolPipedreamConnection,
ToolPipelineService, ToolPipelineToolContext, ToolPipelineWorkflows, ToolProjectService,
- ToolProjectToolContext, ToolPropertiesService, ToolPropertiesToolContext, ToolServiceContext,
- ToolSkillService, ToolSkillToolContext, ToolSoupService, ToolSystemPropertiesService,
- ToolTableEventPublisher, ToolTeamCalendarService, ToolTeamCalendarToolContext, ToolTeamService,
- ToolTeamToolContext, ToolUserEmailService, ToolViewOnlyDatabasesSqlToolContext,
- build_activity_tool_context, build_booking_link_tool_context,
- build_booking_management_tool_context, build_bot_tool_context, build_calendar_tool_context,
- build_channel_media_upload_tool_context, build_channel_tool_context_with_dispatcher,
- build_channel_tool_context_with_side_effects, build_channel_tool_context_without_side_effects,
- build_coding_agent_tool_context, build_crm_tool_context, build_crm_transfer_tool_context,
- build_databases_sql_tool_context, build_databases_tool_context, build_favorites_service,
- build_favorites_tool_context, build_forms_tool_context, build_image_generation_tool_context,
- build_initiative_tool_context, build_item_notification_preference_tool_context,
- build_message_service_with_side_effects, build_message_service_without_side_effects,
- build_pipeline_tool_context, build_project_tool_context, build_properties_service,
- build_properties_service_with_broker, build_properties_tool_context,
- build_routine_tool_context, build_skill_tool_context, build_task_properties_adapter,
- build_team_calendar_tool_context, build_team_repository, build_team_tool_context,
+ ToolProjectToolContext, ToolPropertiesService, ToolPropertiesToolContext,
+ ToolReadAgentSessionContext, ToolServiceContext, ToolSkillService, ToolSkillToolContext,
+ ToolSoupService, ToolSystemPropertiesService, ToolTableEventPublisher, ToolTeamCalendarService,
+ ToolTeamCalendarToolContext, ToolTeamService, ToolTeamToolContext, ToolUserEmailService,
+ ToolViewOnlyDatabasesSqlToolContext, build_activity_tool_context,
+ build_booking_link_tool_context, build_booking_management_tool_context, build_bot_tool_context,
+ build_calendar_tool_context, build_channel_media_upload_tool_context,
+ build_channel_tool_context_with_dispatcher, build_channel_tool_context_with_side_effects,
+ build_channel_tool_context_without_side_effects, build_coding_agent_tool_context,
+ build_crm_tool_context, build_crm_transfer_tool_context, build_databases_sql_tool_context,
+ build_databases_tool_context, build_favorites_service, build_favorites_tool_context,
+ build_forms_tool_context, build_image_generation_tool_context, build_initiative_tool_context,
+ build_item_notification_preference_tool_context, build_message_service_with_side_effects,
+ build_message_service_without_side_effects, build_pipeline_tool_context,
+ build_project_tool_context, build_properties_service, build_properties_service_with_broker,
+ build_properties_tool_context, build_read_agent_session_context, build_routine_tool_context,
+ build_skill_tool_context, build_task_properties_adapter, build_team_calendar_tool_context,
+ build_team_repository, build_team_tool_context,
};
pub use tool_context::{ToolConnectorToolContext, build_connector_tool_context};
#[cfg(any(test, feature = "test-support"))]
@@ -166,7 +168,9 @@ pub(crate) fn subagent_toolset() -> AiToolSet {
.add_subtoolset::<ToolInitiativeToolContext>(initiative_toolset())
.add_subtoolset::<ToolPropertiesToolContext>(properties_toolset())
.add_subtoolset::<ToolCallToolContext>(call_toolset())
- .add_subtoolset::<ToolChatToolContext>(chat_toolset())
+ .add_tool::<ReadAgentSession, ToolReadAgentSessionContext>()
+ .add_tool::<agent_session::inbound::toolset::ReadAgentSessionSharing, ToolReadAgentSessionContext>()
+ .add_tool::<agent_session::inbound::toolset::UpdateAgentSessionSharing, ToolReadAgentSessionContext>()
.add_subtoolset::<ToolChannelToolContext>(channel_toolset())
.add_subtoolset::<ToolBotToolContext>(bot_toolset())
.add_subtoolset::<ToolTeamToolContext>(team_toolset())
@@ -231,9 +235,9 @@ pub const EAGER_TOOLS: &[&str] = &[
"LoadTools",
"NameSearch",
"ReadChannelMessageContext",
+ "ReadAgentSession",
"ReadChannelMessages",
"ReadChannelThread",
- "ReadChat",
"ReadContent",
"ReadMetadata",
"ReadSkill",
@@ -381,7 +385,13 @@ pub fn all_tool_frontend_schemas() -> FrontendSchemas {
frontend_schemas_builder()
.merge(&tools_for(AiHost::AgentSession))
.merge(&agent_code_mode::inbound::toolset::toolset())
+ // Persisted legacy calls still render, but are never executable or advertised.
+ .merge(&chat::inbound::toolset::chat_toolset::<
+ ToolChatService,
+ ToolEntityAccessService,
+ >())
.merge(&read::read_thread())
+ .merge(&frontend_compat::LegacyConversationSchemas)
.build()
}
diff --git a/crates/ai_tools/src/search/search_service/content.rs b/crates/ai_tools/src/search/search_service/content.rs
index 494c7f7268..2cd8f74226 100644
--- a/crates/ai_tools/src/search/search_service/content.rs
+++ b/crates/ai_tools/src/search/search_service/content.rs
@@ -1,7 +1,7 @@
use super::context::SearchToolContext;
use super::types::{
- PAGE_SIZE, SearchMatchType, SearchToolResponse, annotate_result_tags, resolve_tag_filters,
- tag_filter_mode,
+ PAGE_SIZE, SearchEntityType, SearchMatchType, SearchToolResponse, annotate_result_tags,
+ resolve_tag_filters, search_filters, tag_filter_mode,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -10,9 +10,7 @@ use email::domain::ports::EmailService;
use item_filters::{EmailFilters, EntityFilters};
use macro_user_id::user_id::MacroUserIdStr;
use models_properties::service::tag_sets::{TagFilter, TagMatch};
-use models_search::unified::{
- UnifiedSearchIndex, UnifiedSearchRequest, entity_filters_from_include,
-};
+use models_search::unified::UnifiedSearchRequest;
use schemars::JsonSchema;
use serde::Deserialize;
use uuid::Uuid;
@@ -20,12 +18,12 @@ use uuid::Uuid;
#[derive(Debug, JsonSchema, Deserialize, Clone)]
#[serde(rename_all = "camelCase")]
#[schemars(
- description = "Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; chat messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For chats, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).",
+ description = "Search items by their content: document body text; email subject/body/sender/recipient/cc/bcc and the display names on those addresses; agent session messages; call transcripts. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed content. Use this for targeted keyword/content lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. Whitespace-separated terms are ANDed. For documents and emails, every term must match somewhere in the document — different terms can appear in different chunks/pages or different fields. For documents and emails specifically, each single-word term is matched as a prefix (so `scri` matches `script`); for emails the prefix expansion also runs against the local-part of address fields. For agent sessions, channels, and call transcripts the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the content, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion (e.g. an exact word, identifier, or full email address). Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).",
title = "ContentSearch"
)]
pub struct ContentSearch {
#[schemars(
- description = "The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For chats/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix."
+ description = "The text to search. Pass 1-3 keywords drawn from words that would literally appear in the content, not the user's natural-language description. Whitespace-separated terms are ANDed. For documents, every term must appear somewhere in the document (different chunks/pages are fine). For emails each term is matched across subject/body/sender/recipient. For sessions/channels/calls the whole query is matched as a single adjacent phrase prefix, so long phrases will not match. Wrap a multi-word phrase in double quotes to match it as one phrase. Use matchType 'exact' for whole-token (or full email address) matching instead of prefix."
)]
pub query: String,
@@ -39,7 +37,7 @@ pub struct ContentSearch {
description = "Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']. Projects and calendar events carry no indexed content, so they never match here — search those by name with NameSearch instead."
)]
#[serde(default)]
- pub entity_types: Vec<UnifiedSearchIndex>,
+ pub entity_types: Vec<SearchEntityType>,
#[schemars(
description = "Search only the transcripts of these agent sessions, by id, and nothing else. Use it with your own session id to find the exact words of something said earlier in your conversation, including parts that were summarized to keep it within your context. Omit to search every type."
@@ -59,7 +57,7 @@ them with tagsMatch=\"all\". Each entry names a tag by its label, matched case-i
against the user's own tags; only set scope (\"personal\" or \"team\") when the user \
distinguishes between their personal and team tags. An unknown label fails with the list of \
available tags — call ListTags first when unsure what tags exist. Only taggable items \
-(documents, emails, AI chats, projects, call records) can match, so channels are dropped \
+(documents, emails, projects, call records) can match, so channels are dropped \
while a tag filter is active.")]
#[serde(default)]
pub tags: Option<Vec<TagFilter>>,
@@ -76,14 +74,14 @@ Ignored unless tags is set.")]
/// Which items a content search reaches: the named agent sessions alone
/// when it names any, otherwise the requested types.
fn content_filters(
- entity_types: &[UnifiedSearchIndex],
+ entity_types: &[SearchEntityType],
agent_session_ids: &[Uuid],
base: EntityFilters,
) -> EntityFilters {
if agent_session_ids.is_empty() {
- return entity_filters_from_include(entity_types.to_vec(), base);
+ return search_filters(entity_types, base);
}
- let mut filters = entity_filters_from_include(vec![UnifiedSearchIndex::AgentSessions], base);
+ let mut filters = search_filters(&[SearchEntityType::AgentSessions], base);
filters.agent_session_filters.ids = agent_session_ids.iter().map(Uuid::to_string).collect();
filters
}
diff --git a/crates/ai_tools/src/search/search_service/name.rs b/crates/ai_tools/src/search/search_service/name.rs
index 4eb9476bdc..15760d9f1b 100644
--- a/crates/ai_tools/src/search/search_service/name.rs
+++ b/crates/ai_tools/src/search/search_service/name.rs
@@ -1,7 +1,7 @@
use super::context::SearchToolContext;
use super::types::{
- PAGE_SIZE, SearchMatchType, SearchToolResponse, annotate_result_tags, resolve_tag_filters,
- tag_filter_mode,
+ PAGE_SIZE, SearchEntityType, SearchMatchType, SearchToolResponse, annotate_result_tags,
+ resolve_tag_filters, search_filters, tag_filter_mode,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -11,17 +11,14 @@ use item_filters::{EmailFilters, EntityFilters};
use macro_user_id::user_id::MacroUserIdStr;
use models_properties::service::tag_sets::{TagFilter, TagMatch};
use models_search::channel::ChannelNameSearchRequest;
-use models_search::unified::{
- UnifiedSearchIndex, UnifiedSearchRequest, UnifiedSearchResponseItem,
- entity_filters_from_include,
-};
+use models_search::unified::{UnifiedSearchRequest, UnifiedSearchResponseItem};
use schemars::JsonSchema;
use serde::Deserialize;
#[derive(Debug, JsonSchema, Deserialize, Clone)]
#[serde(rename_all = "camelCase")]
#[schemars(
- description = "Search items by their name or title: document name, email subject, chat title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, AI chats, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).",
+ description = "Search items by their name or title: document name, email subject, agent session title, channel name, project name, or call-record name. This is keyword search, not semantic search: queries only match literal words/tokens, prefixes, or exact quoted terms that appear in the indexed title/name. Use this for targeted name/title lookup, not for activity-summary questions like \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; those should start with ListEntities using time/type/channel filters. For emails, whitespace-separated terms are ANDed and each is a prefix match against the subject. For all other types the whole query is matched as a single adjacent phrase prefix — so pass 1-3 targeted keywords drawn from words that would literally appear in the title, not the user's natural-language description; long phrases will not match. Matching defaults to prefix; set matchType to 'exact' to match whole tokens/phrases with no prefix expansion. Wrap a multi-word phrase in double quotes to keep it together as one adjacent phrase. If the user's request combines a person with a topic, run separate searches (NameSearch for the person, ContentSearch for the topic) rather than one combined query. Leave entityTypes empty by default; only filter when the user explicitly scopes to a type. Results for documents, emails, projects, and call records include the tags visible to the user as {label, scope} pairs; to restrict a search to tagged items, pass the tag labels in the tags argument (ListTags shows which tags exist).",
title = "NameSearch"
)]
pub struct NameSearch {
@@ -40,7 +37,7 @@ pub struct NameSearch {
description = "Which types of items to search. Leave empty (the default) to search all types — this is almost always what you want. Only set this when the user's request clearly targets one or more specific types. Examples: ['documents'], ['emails', 'documents'], ['channels'], ['call_records']."
)]
#[serde(default)]
- pub entity_types: Vec<UnifiedSearchIndex>,
+ pub entity_types: Vec<SearchEntityType>,
#[schemars(
description = "Restrict email results to a single connected inbox, given as that inbox's email address (from ListInboxes). Omit to search every inbox the user can access. Only set this when the user scopes the request to a specific mailbox. Only affects email results."
@@ -54,7 +51,7 @@ them with tagsMatch=\"all\". Each entry names a tag by its label, matched case-i
against the user's own tags; only set scope (\"personal\" or \"team\") when the user \
distinguishes between their personal and team tags. An unknown label fails with the list of \
available tags — call ListTags first when unsure what tags exist. Only taggable items \
-(documents, emails, AI chats, projects, call records, calendar events) can match, so \
+(documents, emails, projects, call records, calendar events) can match, so \
channels are dropped \
while a tag filter is active.")]
#[serde(default)]
@@ -141,26 +138,27 @@ impl AsyncTool<SearchToolContext> for NameSearch {
};
let non_channel_types = if self.entity_types.is_empty() {
vec![
- UnifiedSearchIndex::Documents,
- UnifiedSearchIndex::Chats,
- UnifiedSearchIndex::Emails,
- UnifiedSearchIndex::Projects,
- UnifiedSearchIndex::CallRecords,
+ SearchEntityType::Documents,
+ SearchEntityType::AgentSessions,
+ SearchEntityType::Emails,
+ SearchEntityType::Projects,
+ SearchEntityType::CallRecords,
+ SearchEntityType::CalendarEvents,
]
} else {
self.entity_types
.iter()
- .filter(|entity_type| **entity_type != UnifiedSearchIndex::Channels)
+ .filter(|entity_type| **entity_type != SearchEntityType::Channels)
.cloned()
.collect()
};
let include_channels = !tag_filter_active
&& (self.entity_types.is_empty()
- || self.entity_types.contains(&UnifiedSearchIndex::Channels));
+ || self.entity_types.contains(&SearchEntityType::Channels));
let search_request = (!non_channel_types.is_empty()).then(|| UnifiedSearchRequest {
query: self.name.to_owned(),
match_type: self.match_type.into(),
- filters: entity_filters_from_include(non_channel_types, base_filters),
+ filters: search_filters(&non_channel_types, base_filters),
search_on: models_search::SearchOn::Name,
include_crm: false,
collapse: None,
diff --git a/crates/ai_tools/src/search/search_service/types.rs b/crates/ai_tools/src/search/search_service/types.rs
index 8abaaa9a8c..b6b69a0292 100644
--- a/crates/ai_tools/src/search/search_service/types.rs
+++ b/crates/ai_tools/src/search/search_service/types.rs
@@ -12,6 +12,78 @@ use serde::{Deserialize, Serialize};
use super::context::SearchToolContext;
+/// Searchable entities exposed to agents. Legacy conversations are not tool targets.
+#[derive(Debug, Clone, Copy, Deserialize, JsonSchema, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SearchEntityType {
+ AgentSessions,
+ Documents,
+ Emails,
+ Channels,
+ Projects,
+ CallRecords,
+ CalendarEvents,
+}
+
+impl From<SearchEntityType> for models_search::unified::UnifiedSearchIndex {
+ fn from(value: SearchEntityType) -> Self {
+ match value {
+ SearchEntityType::AgentSessions => Self::AgentSessions,
+ SearchEntityType::Documents => Self::Documents,
+ SearchEntityType::Emails => Self::Emails,
+ SearchEntityType::Channels => Self::Channels,
+ SearchEntityType::Projects => Self::Projects,
+ SearchEntityType::CallRecords => Self::CallRecords,
+ SearchEntityType::CalendarEvents => Self::CalendarEvents,
+ }
+ }
+}
+
+/// Explicitly exclude legacy chats even when no type filter was supplied.
+pub(super) fn search_filters(
+ types: &[SearchEntityType],
+ base: item_filters::EntityFilters,
+) -> item_filters::EntityFilters {
+ let mut filters = models_search::unified::entity_filters_from_include(
+ types.iter().copied().map(Into::into).collect(),
+ base,
+ );
+ filters.chat_filters.chat_ids = vec![uuid::Uuid::nil().to_string()];
+ filters
+}
+
+/// Search results agents can act on.
+#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase", tag = "type")]
+pub enum SessionAwareSearchResult {
+ Document(models_search::document::DocumentSearchResponseItemWithMetadata),
+ Email(models_search::email::EmailSearchResponseItemWithMetadata),
+ ChannelMessage(models_search::channel::ChannelMessageSearchResponseItem),
+ Channel(models_search::channel::ChannelNameSearchResponseItem),
+ Project(models_search::project::ProjectSearchResponseItemWithMetadata),
+ Call(models_search::call_record::CallRecordSearchResponseItemWithMetadata),
+ Company(models_search::crm_company::CrmCompanySearchResponseItem),
+ CalendarEvent(models_search::calendar_event::CalendarEventSearchResponseItemWithMetadata),
+ AgentSession(models_search::agent_session::AgentSessionSearchResponseItem),
+}
+
+impl SessionAwareSearchResult {
+ fn from_unified(item: UnifiedSearchResponseItem) -> Option<Self> {
+ Some(match item {
+ UnifiedSearchResponseItem::Chat(_) => return None,
+ UnifiedSearchResponseItem::Document(item) => Self::Document(item),
+ UnifiedSearchResponseItem::Email(item) => Self::Email(item),
+ UnifiedSearchResponseItem::ChannelMessage(item) => Self::ChannelMessage(item),
+ UnifiedSearchResponseItem::Channel(item) => Self::Channel(item),
+ UnifiedSearchResponseItem::Project(item) => Self::Project(item),
+ UnifiedSearchResponseItem::Call(item) => Self::Call(item),
+ UnifiedSearchResponseItem::Company(item) => Self::Company(item),
+ UnifiedSearchResponseItem::CalendarEvent(item) => Self::CalendarEvent(item),
+ UnifiedSearchResponseItem::AgentSession(item) => Self::AgentSession(item),
+ })
+ }
+}
+
pub const PAGE_SIZE: i64 = 50;
/// How search tools match query terms. Restricted to partial/exact — the
@@ -38,10 +110,10 @@ impl From<SearchMatchType> for MatchType {
/// A search result annotated with the caller-visible tags on the item.
#[derive(Serialize, Deserialize, Debug, JsonSchema)]
-pub struct TaggedSearchResult {
+pub struct TaggedSessionAwareSearchResult {
/// The search result itself.
#[serde(flatten)]
- pub item: UnifiedSearchResponseItem,
+ pub item: SessionAwareSearchResult,
/// Tags on this item visible to the user.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<AppliedTag>,
@@ -49,7 +121,7 @@ pub struct TaggedSearchResult {
#[derive(Serialize, Deserialize, Debug, JsonSchema)]
pub struct SearchToolResponse {
- pub results: Vec<TaggedSearchResult>,
+ pub results: Vec<TaggedSessionAwareSearchResult>,
}
/// Map the model-facing tag match mode onto the search request's filter mode.
@@ -101,7 +173,7 @@ pub(super) async fn annotate_result_tags(
user_id: &str,
results: Vec<UnifiedSearchResponseItem>,
tag_sets: Option<CallerTagSets>,
-) -> ToolResult<Vec<TaggedSearchResult>> {
+) -> ToolResult<Vec<TaggedSessionAwareSearchResult>> {
let any_tags = results.iter().any(|item| {
item_properties(item).is_some_and(|props| {
props
@@ -122,7 +194,7 @@ pub(super) async fn annotate_result_tags(
Ok(results
.into_iter()
- .map(|mut item| {
+ .filter_map(|mut item| {
let mut tags: Vec<AppliedTag> = Vec::new();
if let Some(props) = item_properties_mut(&mut item) {
for property in props.iter() {
@@ -142,7 +214,10 @@ pub(super) async fn annotate_result_tags(
}
props.retain(|p| p.definition.data_type != DataType::Tag);
}
- TaggedSearchResult { item, tags }
+ Some(TaggedSessionAwareSearchResult {
+ item: SessionAwareSearchResult::from_unified(item)?,
+ tags,
+ })
})
.collect())
}
@@ -191,3 +266,6 @@ fn item_properties_mut(item: &mut UnifiedSearchResponseItem) -> Option<&mut Vec<
| UnifiedSearchResponseItem::Company(_) => None,
}
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/ai_tools/src/search/search_service/types/test.rs b/crates/ai_tools/src/search/search_service/types/test.rs
new file mode 100644
index 0000000000..d6080e7b8f
--- /dev/null
+++ b/crates/ai_tools/src/search/search_service/types/test.rs
@@ -0,0 +1,21 @@
+use super::*;
+
+#[test]
+fn searches_include_sessions_by_default_and_never_include_legacy_chats() {
+ let filters = search_filters(&[], item_filters::EntityFilters::default());
+ assert!(filters.agent_session_filters.include);
+ assert_eq!(
+ filters.chat_filters.chat_ids,
+ vec![uuid::Uuid::nil().to_string()]
+ );
+ let filters = search_filters(
+ &[SearchEntityType::AgentSessions],
+ item_filters::EntityFilters::default(),
+ );
+ assert!(filters.agent_session_filters.include);
+ assert_eq!(
+ filters.document_filters.document_ids,
+ vec![uuid::Uuid::nil().to_string()]
+ );
+ assert!(serde_json::from_str::<SearchEntityType>("\"chats\"").is_err());
+}
diff --git a/crates/ai_tools/src/self_knowledge.rs b/crates/ai_tools/src/self_knowledge.rs
index d2cd9b6545..96d2f88b31 100644
--- a/crates/ai_tools/src/self_knowledge.rs
+++ b/crates/ai_tools/src/self_knowledge.rs
@@ -28,14 +28,13 @@ Macro is organized into "blocks":
- **Email** — email, integrated directly into the workspace.
- **Channels** — Slack-like messaging channels; the default way people communicate.
-- **Chat** — AI conversations (this is what "chat" refers to).
- **Tasks** — task and project tracking.
- **Docs** — collaborative documents.
- **Canvas** — a freeform visual canvas.
- **Calls** — calls and call records.
- **CRM** — customer relationship management.
- **Folders** — file storage.
-- **Agents** — AI agents that can act across the workspace.
+- **Agents** — AI conversations and coding sessions that can act across the workspace. Read conversations with ReadAgentSession.
Cross-cutting concepts: the **Unified Inbox** (recent items across every block,
read via the ListEntities tool), **Unified Search**, **Unified Memory**,
diff --git a/crates/ai_tools/src/test.rs b/crates/ai_tools/src/test.rs
index c48ab0dfd5..a2a8a5523d 100644
--- a/crates/ai_tools/src/test.rs
+++ b/crates/ai_tools/src/test.rs
@@ -596,7 +596,7 @@ fn code_mode_retains_direct_lifecycles_and_hides_sdk_methods_from_lazy_discovery
let direct = tools_for_agent_code_mode();
let sdk = code_mode_tools();
assert!(direct.toolset.tools.len() < standard.toolset.tools.len());
- for name in ["NameSearch", "ReadContent", "ListEntities"] {
+ for name in ["ReadContent"] {
assert!(standard.toolset.tools.contains_key(name), "{name}");
assert!(sdk.tools.contains_key(name), "{name}");
assert!(!direct.toolset.tools.contains_key(name), "{name}");
@@ -604,6 +604,8 @@ fn code_mode_retains_direct_lifecycles_and_hides_sdk_methods_from_lazy_discovery
}
for name in [
"DisplayResults",
+ "NameSearch",
+ "ListEntities",
"ContentSearch",
"CreateDocument",
"ListSkills",
@@ -647,24 +649,14 @@ fn code_mode_retains_direct_lifecycles_and_hides_sdk_methods_from_lazy_discovery
);
let deferred = DeferredToolSet::new(direct.toolset.clone(), direct.deferred.clone());
let eager = deferred.request_schemas().unwrap();
- assert!(!eager.iter().any(|schema| schema.name == "ListEntities"));
- for name in ["ContentSearch", "EditDocument"] {
+ for name in [
+ "ListEntities",
+ "NameSearch",
+ "ContentSearch",
+ "EditDocument",
+ ] {
assert!(eager.iter().any(|schema| schema.name == name), "{name}");
}
- assert!(
- deferred
- .searchable_catalog()
- .iter()
- .all(|tool| tool.name != "ListEntities")
- );
- assert!(deferred.routing_description("ListEntities").is_none());
- assert!(deferred.routing_description("NameSearch").is_none());
- assert!(
- deferred
- .searchable_catalog()
- .iter()
- .all(|t| t.name != "NameSearch")
- );
for name in ["SendEmail", "CreateCalendarEvent"] {
assert!(standard.toolset.tools.contains_key(name));
assert!(sdk.tools.contains_key(name));
@@ -683,3 +675,92 @@ fn code_mode_retains_direct_lifecycles_and_hides_sdk_methods_from_lazy_discovery
assert!(!tools_for(host).prompt.to_string().contains(&routing));
}
}
+
+#[test]
+fn session_reader_is_available_to_every_conversation_host_and_mcp() {
+ for host in [
+ AiHost::Chat,
+ AiHost::AgentSession,
+ AiHost::ChannelBot,
+ AiHost::Mcp,
+ ] {
+ let tools = tools_for(host);
+ assert!(tools.toolset.tools.contains_key("ReadAgentSession"));
+ assert!(
+ !tools
+ .deferred
+ .iter()
+ .any(|tool| tool.name == "ReadAgentSession")
+ );
+ }
+ assert!(subagent_toolset().tools.contains_key("ReadAgentSession"));
+ let code_mode = tools_for_agent_code_mode();
+ assert!(code_mode.toolset.tools.contains_key("ReadAgentSession"));
+ assert!(
+ !code_mode
+ .deferred
+ .iter()
+ .any(|tool| tool.name == "ReadAgentSession")
+ );
+}
+
+#[test]
+fn conversation_tools_only_advertise_new_sessions() {
+ for tools in [
+ tools_for(AiHost::Chat),
+ tools_for(AiHost::AgentSession),
+ tools_for(AiHost::ChannelBot),
+ tools_for(AiHost::Mcp),
+ tools_for_agent_code_mode(),
+ ] {
+ assert!(!tools.toolset.tools.contains_key("ReadChat"));
+ assert!(!tools.prompt.to_string().contains("ReadChat"));
+ for name in [
+ "ReadAgentSession",
+ "ReadAgentSessionSharing",
+ "UpdateAgentSessionSharing",
+ "CreateAgentSession",
+ "ManageAgentSession",
+ ] {
+ assert!(tools.toolset.tools.contains_key(name), "missing {name}");
+ }
+ for schema in tools.toolset.request_schemas().unwrap() {
+ let json = serde_json::to_string(&schema.schema).unwrap();
+ if [
+ "NameSearch",
+ "ContentSearch",
+ "ListEntities",
+ "RenameItem",
+ "MoveToTrash",
+ "MoveToProject",
+ "DuplicateItem",
+ "UpdateSharing",
+ "ShareWithChannel",
+ "SetFavorite",
+ "GetEntityProperties",
+ "SetEntityProperty",
+ "BulkSetEntityPropertyOptions",
+ "ListNotifications",
+ ]
+ .contains(&schema.name.as_str())
+ {
+ assert!(
+ !json.contains("\"chat\""),
+ "{} advertises legacy chats",
+ schema.name
+ );
+ assert!(
+ !json.contains("\"chats\""),
+ "{} advertises legacy chat search",
+ schema.name
+ );
+ assert!(
+ !json.contains("\"ai_chat\""),
+ "{} advertises legacy chat listing",
+ schema.name
+ );
+ }
+ }
+ }
+ assert!(!subagent_toolset().tools.contains_key("ReadChat"));
+}
diff --git a/crates/ai_tools/src/tool_context.rs b/crates/ai_tools/src/tool_context.rs
index 25c2d5abaf..187e1be181 100644
--- a/crates/ai_tools/src/tool_context.rs
+++ b/crates/ai_tools/src/tool_context.rs
@@ -83,7 +83,9 @@ pub use channel_media::build_channel_media_upload_tool_context_test;
pub use channel_media::{
ToolChannelMediaUploadToolContext, build_channel_media_upload_tool_context,
};
+mod agent_sessions;
mod coding_agents;
+pub use agent_sessions::{ToolReadAgentSessionContext, build_read_agent_session_context};
pub use coding_agents::{ToolCodingAgentToolContext, build_coding_agent_tool_context};
mod images;
#[cfg(any(test, feature = "test-support"))]
@@ -1371,19 +1373,17 @@ pub type ToolProjectToolContext = ProjectToolContext<
ToolProjectService,
ToolEntityAccessService,
ToolDocumentService,
- ToolChatService,
ToolUserEmailService,
>;
/// Build the project tool context from shared domain and access services.
-/// The move services must be the same instances the document, chat, and
+/// The move services must be the same instances the document and
/// email tool contexts run on so moves share their side-effect wiring.
pub fn build_project_tool_context(
pool: sqlx::PgPool,
macro_event_broker: ToolEventBroker,
entity_access_service: Arc<ToolEntityAccessService>,
document_service: Arc<ToolDocumentService>,
- chat_service: Arc<ToolChatService>,
email_service: Arc<ToolUserEmailService>,
) -> ToolProjectToolContext {
let project_service = projects::domain::service::ProjectServiceImpl::new(
@@ -1405,7 +1405,6 @@ pub fn build_project_tool_context(
Arc::new(project_service),
entity_access_service,
document_service,
- chat_service,
email_service,
)
}
@@ -1829,6 +1828,8 @@ pub struct ToolServiceContext {
pub channel_media_upload_tool_context: ToolChannelMediaUploadToolContext,
pub bot_tool_context: ToolBotToolContext,
pub coding_agent_tool_context: ToolCodingAgentToolContext,
+ /// Authorized agent-session conversation reads.
+ pub read_agent_session_context: ToolReadAgentSessionContext,
pub project_tool_context: ToolProjectToolContext,
/// Favorite toggles; the same favorites back `soup_service`'s favorites filter.
pub favorites_tool_context: ToolFavoritesToolContext,
diff --git a/crates/ai_tools/src/tool_context/agent_sessions.rs b/crates/ai_tools/src/tool_context/agent_sessions.rs
new file mode 100644
index 0000000000..b4cf5c12b8
--- /dev/null
+++ b/crates/ai_tools/src/tool_context/agent_sessions.rs
@@ -0,0 +1,31 @@
+//! Wire the session reader to the shared session repository and access service.
+
+use super::ToolEntityAccessService;
+use agent_session::{
+ domain::read::SessionReader, inbound::toolset::ReadAgentSessionContext,
+ outbound::postgres::PgAgentSessionRepo,
+};
+use bots::outbound::pg_bots_repo::PgBotsRepo;
+use entity_registry::OwnerGrantPolicy;
+use entity_registry_db_utils::OwnedEntityRegistrar;
+use std::sync::Arc;
+
+/// Session-reading dependencies shared by chat, agents, and external MCP.
+pub type ToolReadAgentSessionContext =
+ ReadAgentSessionContext<PgAgentSessionRepo<PgBotsRepo>, ToolEntityAccessService>;
+
+/// Reuse the session domain's repository and the host's entity-access service.
+pub fn build_read_agent_session_context(
+ pool: sqlx::PgPool,
+ access: Arc<ToolEntityAccessService>,
+) -> ToolReadAgentSessionContext {
+ let registrar = OwnedEntityRegistrar::new(OwnerGrantPolicy::new(PgBotsRepo::new(pool.clone())));
+ let repo = PgAgentSessionRepo::new(pool, registrar);
+ ReadAgentSessionContext {
+ sharing: Arc::new(agent_session::domain::sharing::SessionSharingService::new(
+ repo.clone(),
+ )),
+ service: Arc::new(SessionReader::new(repo)),
+ access,
+ }
+}
diff --git a/crates/ai_tools/src/tool_context/coding_agents.rs b/crates/ai_tools/src/tool_context/coding_agents.rs
index 7abe2120fd..f00592e065 100644
--- a/crates/ai_tools/src/tool_context/coding_agents.rs
+++ b/crates/ai_tools/src/tool_context/coding_agents.rs
@@ -16,6 +16,7 @@ pub fn build_coding_agent_tool_context(
let client = CodingAgentsClient::new(url.as_ref(), &internal_api_key)
.map_err(|error| anyhow::anyhow!("{error}"))?;
Ok(ToolCodingAgentToolContext {
+ sessions: Arc::new(client.clone()),
service: Arc::new(client),
})
}
diff --git a/crates/channels/AGENTS.md b/crates/channels/AGENTS.md
index 47965517f2..c081b37436 100644
--- a/crates/channels/AGENTS.md
+++ b/crates/channels/AGENTS.md
@@ -42,6 +42,10 @@ DMs, and the shared message store other domains discuss things on.
`src/outbound/connection_gateway_realtime.rs`.
- Add a channel-message AI tool: `src/inbound/toolset.rs` (feature `ai_tools`).
+## Tool contracts
+
+- `ShareWithChannel` exposes agent sessions and omits legacy chat targets; the domain retains historical entity support.
+
## Checks
- `cargo test -p channels` (`SQLX_OFFLINE` unset).
diff --git a/crates/channels/src/inbound/toolset/share_with_channel.rs b/crates/channels/src/inbound/toolset/share_with_channel.rs
index a67753ab59..7a289f4dcc 100644
--- a/crates/channels/src/inbound/toolset/share_with_channel.rs
+++ b/crates/channels/src/inbound/toolset/share_with_channel.rs
@@ -27,8 +27,6 @@ pub enum ChannelShareEntityType {
CalendarEvent,
/// A document.
Document,
- /// An AI chat.
- Chat,
/// A project.
Project,
/// A database.
@@ -49,7 +47,6 @@ impl ChannelShareEntityType {
match self {
Self::CalendarEvent => ReferencedShareItemType::CalendarEvent,
Self::Document => ReferencedShareItemType::Document,
- Self::Chat => ReferencedShareItemType::Chat,
Self::Project => ReferencedShareItemType::Project,
Self::Database => ReferencedShareItemType::Database,
Self::Form => ReferencedShareItemType::Form,
@@ -75,7 +72,7 @@ impl ChannelShareEntityType {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "ShareWithChannel",
- description = "Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, chat, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists."
+ description = "Share an item with the current members of a channel by writing a channel entity-access grant. Call it only after the user agrees to share that item, or when they already asked you to share it. entityType is the stored type: calendar_event for a calendar chip, document, project, database, form, call, thread, or agent_session. entityId is that item's id. A calendar event can be shared only by someone who holds it on their own calendar, and private or confidential events are refused. Sharing again is safe when a grant already exists."
)]
pub struct ShareWithChannel {
/// Channel whose current members should receive the grant.
@@ -88,7 +85,7 @@ pub struct ShareWithChannel {
pub entity_id: String,
/// Stored entity type of the item.
#[schemars(
- description = "Stored entity type: calendar_event, document, chat, project, database, form, call, thread, or agent_session."
+ description = "Stored entity type: calendar_event, document, project, database, form, call, thread, or agent_session."
)]
pub entity_type: ChannelShareEntityType,
}
diff --git a/crates/favorites/AGENTS.md b/crates/favorites/AGENTS.md
index c4574fa228..9dc0764964 100644
--- a/crates/favorites/AGENTS.md
+++ b/crates/favorites/AGENTS.md
@@ -34,6 +34,10 @@ hexagonal architecture pattern.
→ `src/outbound/pg_favorites_repo.rs` → caller's feature wiring.
- Add an AI tool action: `src/inbound/toolset.rs` → `src/domain/mutation_service.rs`.
+## Tool contracts
+
+- The AI adapter omits legacy chat targets; only advertise entity types supported by the domain mutation service.
+
## Checks
- `cargo test -p favorites --all-features` (`SQLX_OFFLINE` unset).
diff --git a/crates/favorites/src/inbound/toolset.rs b/crates/favorites/src/inbound/toolset.rs
index 38173a2145..5342be25ec 100644
--- a/crates/favorites/src/inbound/toolset.rs
+++ b/crates/favorites/src/inbound/toolset.rs
@@ -55,8 +55,6 @@ pub enum FavoritableEntityType {
Document,
/// A project (folder).
Project,
- /// An AI chat conversation.
- Chat,
/// A channel.
Channel,
/// An email thread.
@@ -74,7 +72,6 @@ impl FavoritableEntityType {
match self {
Self::Document => EntityType::Document,
Self::Project => EntityType::Project,
- Self::Chat => EntityType::Chat,
Self::Channel => EntityType::Channel,
Self::Email => EntityType::EmailThread,
Self::Call => EntityType::Call,
diff --git a/crates/notification/AGENTS.md b/crates/notification/AGENTS.md
index 253b4776c7..b10e6d8ad5 100644
--- a/crates/notification/AGENTS.md
+++ b/crates/notification/AGENTS.md
@@ -54,6 +54,10 @@ through the same service.
(or the relevant inbound adapter) → `src/domain/models.rs` for the event
shape → `src/domain/service.rs`.
+## Tool contracts
+
+- AI notification filters expose agent sessions and omit legacy chat categories and entity targets.
+
## Checks
- `cargo test -p notification --all-features` (`SQLX_OFFLINE` unset; needs local
diff --git a/crates/notification/src/inbound/ai_tool.rs b/crates/notification/src/inbound/ai_tool.rs
index 68d62446ab..92406d3628 100644
--- a/crates/notification/src/inbound/ai_tool.rs
+++ b/crates/notification/src/inbound/ai_tool.rs
@@ -76,8 +76,8 @@ where
#[derive(Debug, Deserialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum NotificationEntityType {
+ AgentSession,
User,
- Chat,
Channel,
#[serde(alias = "message")]
ChannelMessage,
@@ -102,8 +102,8 @@ pub enum NotificationEntityType {
impl From<NotificationEntityType> for EntityType {
fn from(value: NotificationEntityType) -> Self {
match value {
+ NotificationEntityType::AgentSession => Self::AgentSession,
NotificationEntityType::User => Self::User,
- NotificationEntityType::Chat => Self::Chat,
NotificationEntityType::Channel => Self::Channel,
NotificationEntityType::ChannelMessage => Self::ChannelMessage,
NotificationEntityType::Document => Self::Document,
@@ -123,6 +123,51 @@ impl From<NotificationEntityType> for EntityType {
}
}
+/// Notification categories available to agents.
+#[derive(Debug, Deserialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub enum ToolNotificationCategory {
+ /// Email notifications.
+ Email,
+ /// Channel message notifications.
+ Message,
+ /// Channel notifications.
+ Channel,
+ /// Document notifications.
+ Document,
+ /// Folder notifications.
+ Project,
+ /// Call notifications.
+ Call,
+ /// Task notifications.
+ Task,
+ /// GitHub notifications.
+ Github,
+ /// Reminder notifications.
+ Reminder,
+ /// Calendar notifications.
+ Calendar,
+ /// Agent session notifications.
+ Agent,
+}
+impl From<ToolNotificationCategory> for NotificationCategory {
+ fn from(value: ToolNotificationCategory) -> Self {
+ match value {
+ ToolNotificationCategory::Email => Self::Email,
+ ToolNotificationCategory::Message => Self::Message,
+ ToolNotificationCategory::Channel => Self::Channel,
+ ToolNotificationCategory::Document => Self::Document,
+ ToolNotificationCategory::Project => Self::Project,
+ ToolNotificationCategory::Call => Self::Call,
+ ToolNotificationCategory::Task => Self::Task,
+ ToolNotificationCategory::Github => Self::Github,
+ ToolNotificationCategory::Reminder => Self::Reminder,
+ ToolNotificationCategory::Calendar => Self::Calendar,
+ ToolNotificationCategory::Agent => Self::Agent,
+ }
+ }
+}
+
/// User-facing reference to one specific entity to filter notifications by.
#[derive(Debug, Deserialize, JsonSchema, Clone, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
@@ -165,7 +210,7 @@ pub struct ListNotifications {
description = "Filter to specific notification item types. If omitted, returns all types. Example: [\"email\", \"message\"] returns only email and message notifications."
)]
#[serde(default)]
- pub include_types: Option<Vec<NotificationCategory>>,
+ pub include_types: Option<Vec<ToolNotificationCategory>>,
/// Filter to notifications for specific entities. If omitted, returns notifications for all entities.
#[schemars(
@@ -253,7 +298,26 @@ where
states: self.states.clone().unwrap_or_else(|| {
crate::domain::models::NotificationState::ACTIVE.to_vec()
}),
- include_types: self.include_types.clone().unwrap_or_default(),
+ include_types: self
+ .include_types
+ .clone()
+ .filter(|types| !types.is_empty())
+ .map(|types| types.into_iter().map(Into::into).collect())
+ .unwrap_or_else(|| {
+ vec![
+ NotificationCategory::Email,
+ NotificationCategory::Message,
+ NotificationCategory::Channel,
+ NotificationCategory::Document,
+ NotificationCategory::Project,
+ NotificationCategory::Call,
+ NotificationCategory::Task,
+ NotificationCategory::Github,
+ NotificationCategory::Reminder,
+ NotificationCategory::Calendar,
+ NotificationCategory::Agent,
+ ]
+ }),
entities: self
.entities
.clone()
diff --git a/crates/notification/src/inbound/ai_tool/test.rs b/crates/notification/src/inbound/ai_tool/test.rs
index 56b76ab357..ba89f285a8 100644
--- a/crates/notification/src/inbound/ai_tool/test.rs
+++ b/crates/notification/src/inbound/ai_tool/test.rs
@@ -38,9 +38,9 @@ fn test_list_notifications_deserialization() {
assert_eq!(
tool.include_types,
Some(vec![
- NotificationCategory::Email,
- NotificationCategory::Message,
- NotificationCategory::Github
+ ToolNotificationCategory::Email,
+ ToolNotificationCategory::Message,
+ ToolNotificationCategory::Github
])
);
assert_eq!(
diff --git a/crates/projects/AGENTS.md b/crates/projects/AGENTS.md
index c95f31414e..9186ee0361 100644
--- a/crates/projects/AGENTS.md
+++ b/crates/projects/AGENTS.md
@@ -39,6 +39,10 @@ soft delete/restore/purge, and bulk upload into a project tree.
- Add an AI tool: `src/inbound/toolset.rs` → the `ai_tools` feature gate in
`Cargo.toml`.
+## Tool contracts
+
+- AI project tools omit legacy chat targets and results; agent-session lifecycle and sharing belong to `agent_session`.
+
## Checks
- `cargo test -p projects` (`SQLX_OFFLINE` unset; requires local MacroDB).
diff --git a/crates/projects/src/inbound/toolset.rs b/crates/projects/src/inbound/toolset.rs
index 52709ad080..49d7946871 100644
--- a/crates/projects/src/inbound/toolset.rs
+++ b/crates/projects/src/inbound/toolset.rs
@@ -56,42 +56,16 @@ impl<T> DocumentCapabilities for T where
{
}
-/// The entity capabilities project tools dispatch AI chats to.
-pub trait ChatCapabilities:
- MoveEntity
- + RenameEntity
- + TrashEntity
- + DuplicateEntity
- + UpdateEntitySharePolicy
- + Send
- + Sync
- + 'static
-{
-}
-
-impl<T> ChatCapabilities for T where
- T: MoveEntity
- + RenameEntity
- + TrashEntity
- + DuplicateEntity
- + UpdateEntitySharePolicy
- + Send
- + Sync
- + 'static
-{
-}
-
/// Service context for project AI tools.
///
-/// The document and chat services are the per-domain entity-mutation
+/// The document and email services are the per-domain entity-mutation
/// capability impls the move, trash, duplicate, rename, and sharing tools
/// dispatch to, mirroring the DSS entity-mutation router.
-pub struct ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>
+pub struct ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
/// The project service instance.
@@ -100,8 +74,6 @@ where
pub entity_access_service: Arc<ESvc>,
/// Move, trash, duplicate, and sharing capabilities for documents.
pub document_move_service: Arc<DSvc>,
- /// Move, rename, trash, duplicate, and sharing capabilities for AI chats.
- pub chat_move_service: Arc<CSvc>,
/// Move capability for email threads.
pub email_move_service: Arc<EmSvc>,
/// The bot these tools act as, on behalf of the requesting user. Defaults
@@ -109,12 +81,11 @@ where
pub actor: BotId,
}
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> Clone for ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>
+impl<PSvc, ESvc, DSvc, EmSvc> Clone for ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
fn clone(&self) -> Self {
@@ -122,19 +93,17 @@ where
service: self.service.clone(),
entity_access_service: self.entity_access_service.clone(),
document_move_service: self.document_move_service.clone(),
- chat_move_service: self.chat_move_service.clone(),
email_move_service: self.email_move_service.clone(),
actor: self.actor,
}
}
}
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>
+impl<PSvc, ESvc, DSvc, EmSvc> ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
/// Create a new project tool context.
@@ -142,14 +111,12 @@ where
service: Arc<PSvc>,
entity_access_service: Arc<ESvc>,
document_move_service: Arc<DSvc>,
- chat_move_service: Arc<CSvc>,
email_move_service: Arc<EmSvc>,
) -> Self {
Self {
service,
entity_access_service,
document_move_service,
- chat_move_service,
email_move_service,
actor: bot_id::MACRO_AI_BOT_ID,
}
@@ -163,21 +130,20 @@ where
}
/// Create a project toolset.
-pub fn project_toolset<PSvc, ESvc, DSvc, CSvc, EmSvc>()
--> AsyncToolCollection<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
+pub fn project_toolset<PSvc, ESvc, DSvc, EmSvc>()
+-> AsyncToolCollection<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
AsyncToolCollection::new()
- .add_tool::<CreateProject, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<ReadProject, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<MoveToProject, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<MoveToTrash, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<DuplicateItem, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<RenameItem, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
- .add_tool::<UpdateSharing, ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>()
+ .add_tool::<CreateProject, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<ReadProject, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<MoveToProject, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<MoveToTrash, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<DuplicateItem, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<RenameItem, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
+ .add_tool::<UpdateSharing, ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>()
}
diff --git a/crates/projects/src/inbound/toolset/create_project.rs b/crates/projects/src/inbound/toolset/create_project.rs
index 05a7664f29..be26336f0d 100644
--- a/crates/projects/src/inbound/toolset/create_project.rs
+++ b/crates/projects/src/inbound/toolset/create_project.rs
@@ -13,7 +13,7 @@ use model_owner::CreationPrincipal;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
use crate::domain::models::ProjectError;
fn failed_to_create_project(error: ProjectError) -> ToolCallError {
@@ -46,7 +46,7 @@ pub struct CreateProjectResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "CreateProject",
- description = "Create a project — shown as a folder in the app UI. Documents, AI chats, email threads, and other projects can be placed inside it."
+ description = "Create a project — shown as a folder in the app UI. Documents, email threads, and other projects can be placed inside it."
)]
pub struct CreateProject {
/// The name of the project.
@@ -66,13 +66,12 @@ impl ToolAnnotated for CreateProject {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>
for CreateProject
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = CreateProjectResponse;
@@ -80,7 +79,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
tracing::info!(params=?self, "Create project");
diff --git a/crates/projects/src/inbound/toolset/duplicate_item.rs b/crates/projects/src/inbound/toolset/duplicate_item.rs
index 570b2923fd..8a0f09cab0 100644
--- a/crates/projects/src/inbound/toolset/duplicate_item.rs
+++ b/crates/projects/src/inbound/toolset/duplicate_item.rs
@@ -1,4 +1,4 @@
-//! DuplicateItem tool for copying documents and AI chats.
+//! DuplicateItem tool for copying documents.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -10,7 +10,7 @@ use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use super::entity_receipts::{first_updated, mutation_failed, user_receipt};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of item to duplicate.
#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
@@ -18,15 +18,12 @@ use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, Project
pub enum DuplicableEntityType {
/// A document (includes tasks).
Document,
- /// An AI chat conversation.
- Chat,
}
impl DuplicableEntityType {
fn entity_type(self) -> EntityType {
match self {
Self::Document => EntityType::Document,
- Self::Chat => EntityType::Chat,
}
}
}
@@ -72,7 +69,7 @@ pub struct DuplicateItemResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "DuplicateItem",
- description = "Make a copy of a document (including a task) or an AI chat, owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id."
+ description = "Make a copy of a document (including a task), owned by the user, as the Duplicate action in the app does. Requires view access to the original. Returns the copy's id."
)]
pub struct DuplicateItem {
/// The kind of item to duplicate.
@@ -85,7 +82,7 @@ pub struct DuplicateItem {
/// Optional name for the copy.
#[schemars(
- description = "Name for the copy of a document. Omit to use \"<original name> copy\". AI chat copies always keep the original name."
+ description = "Name for the copy of a document. Omit to use \"<original name> copy\"."
)]
#[serde(default)]
pub name: Option<String>,
@@ -96,13 +93,12 @@ impl ToolAnnotated for DuplicateItem {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>
for DuplicateItem
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = DuplicateItemResponse;
@@ -110,7 +106,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, entity_type=?self.entity_type, entity_id=?self.entity_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
let entity = self
@@ -135,17 +131,6 @@ where
)
.await?
}
- // Chat copies keep the source name; the domain rejects a custom one.
- DuplicableEntityType::Chat => {
- duplicate_with(
- &*service_context.chat_move_service,
- access,
- &request_context,
- entity,
- None,
- )
- .await?
- }
};
let copy_id = first_updated(&effects)
.map(|copy| copy.entity_id.to_string())
diff --git a/crates/projects/src/inbound/toolset/move_to_project.rs b/crates/projects/src/inbound/toolset/move_to_project.rs
index fd44fa91cf..dedcbf2555 100644
--- a/crates/projects/src/inbound/toolset/move_to_project.rs
+++ b/crates/projects/src/inbound/toolset/move_to_project.rs
@@ -14,7 +14,7 @@ use model_entity::{Entity, EntityType};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of entity to move.
#[derive(Debug, Deserialize, JsonSchema, Clone, Copy, PartialEq, Eq, Default)]
@@ -23,8 +23,6 @@ pub enum MoveableEntityType {
/// A document (includes tasks).
#[default]
Document,
- /// An AI chat conversation.
- Chat,
/// An email thread.
Email,
/// A project (folder) nested into another project.
@@ -35,7 +33,6 @@ impl MoveableEntityType {
fn entity_type(self) -> EntityType {
match self {
Self::Document => EntityType::Document,
- Self::Chat => EntityType::Chat,
Self::Email => EntityType::EmailThread,
Self::Project => EntityType::Project,
}
@@ -62,7 +59,7 @@ fn project_access_failed(error: AccessError) -> ToolCallError {
fn move_failed(code: EntityMutationErrorCode) -> ToolCallError {
let description = match code {
EntityMutationErrorCode::Forbidden(_) => {
- "you lack the required access: moving an AI chat or project requires owning it, moving a document or email thread requires edit access, and the destination project requires edit access"
+ "you lack the required access: moving a project requires owning it, moving a document or email thread requires edit access, and the destination project requires edit access"
}
EntityMutationErrorCode::NotFound(_) => "the entity or destination project was not found",
EntityMutationErrorCode::Conflict(_) => {
@@ -196,7 +193,7 @@ pub struct MoveToProjectResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "MoveToProject",
- description = "Move a document, AI chat, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving an AI chat or a project requires owning it."
+ description = "Move a document, email thread, or project into another project (projects are shown as folders in the app UI), or move it out to the top level. Requires edit access to the destination project. Moving a document or email thread requires edit access to it; moving a project requires owning it."
)]
pub struct MoveToProject {
/// The kind of entity to move.
@@ -220,13 +217,12 @@ impl ToolAnnotated for MoveToProject {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>
for MoveToProject
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = MoveToProjectResponse;
@@ -234,7 +230,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, entity_type=?self.entity_type, entity_id=?self.entity_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
tracing::info!(params=?self, "Move to project");
@@ -260,17 +256,6 @@ where
)
.await?
}
- MoveableEntityType::Chat => {
- move_with(
- &*service_context.chat_move_service,
- entity_access_service,
- actor,
- &user_id,
- entity,
- project_id,
- )
- .await?
- }
MoveableEntityType::Email => {
move_with(
&*service_context.email_move_service,
diff --git a/crates/projects/src/inbound/toolset/move_to_trash.rs b/crates/projects/src/inbound/toolset/move_to_trash.rs
index 8b03d3c0b3..2acf3b3773 100644
--- a/crates/projects/src/inbound/toolset/move_to_trash.rs
+++ b/crates/projects/src/inbound/toolset/move_to_trash.rs
@@ -1,4 +1,4 @@
-//! MoveToTrash tool for deleting documents, AI chats, and projects to the trash.
+//! MoveToTrash tool for deleting documents and projects to the trash.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -10,7 +10,7 @@ use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use super::entity_receipts::{mutation_failed, user_receipt};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of item to move to the trash.
#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
@@ -18,8 +18,6 @@ use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, Project
pub enum TrashableEntityType {
/// A document (includes tasks).
Document,
- /// An AI chat conversation.
- Chat,
/// A project (folder), with everything inside it.
Project,
}
@@ -28,7 +26,6 @@ impl TrashableEntityType {
fn entity_type(self) -> EntityType {
match self {
Self::Document => EntityType::Document,
- Self::Chat => EntityType::Chat,
Self::Project => EntityType::Project,
}
}
@@ -73,7 +70,7 @@ pub struct MoveToTrashResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "MoveToTrash",
- description = "Delete a document (including a task), an AI chat, or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool."
+ description = "Delete a document (including a task), or a project (folder) by moving it to the trash, as the Delete action in the app does. Trashing a project also trashes everything inside it. Only the item's owner can trash it. Use only when the user explicitly asks to delete an item. Channels, email threads, and calendar events are not deleted with this tool."
)]
pub struct MoveToTrash {
/// The kind of item to trash.
@@ -91,13 +88,11 @@ impl ToolAnnotated for MoveToTrash {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
- for MoveToTrash
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>> for MoveToTrash
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = MoveToTrashResponse;
@@ -105,7 +100,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, entity_type=?self.entity_type, entity_id=?self.entity_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
let entity = self
@@ -123,15 +118,6 @@ where
)
.await?
}
- TrashableEntityType::Chat => {
- trash_with(
- &*service_context.chat_move_service,
- access,
- &request_context,
- entity,
- )
- .await?
- }
TrashableEntityType::Project => {
trash_with(&*service_context.service, access, &request_context, entity).await?
}
diff --git a/crates/projects/src/inbound/toolset/read_project.rs b/crates/projects/src/inbound/toolset/read_project.rs
index 9f98ec2b85..8c645624c6 100644
--- a/crates/projects/src/inbound/toolset/read_project.rs
+++ b/crates/projects/src/inbound/toolset/read_project.rs
@@ -11,7 +11,7 @@ use model_entity::EntityType;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of an item inside a project.
#[derive(Debug, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
@@ -19,8 +19,6 @@ use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, Project
pub enum ProjectItemType {
/// A document (includes tasks).
Document,
- /// An AI chat conversation.
- Chat,
/// A nested project.
Project,
}
@@ -43,9 +41,9 @@ pub struct ProjectItem {
pub updated_at: Option<chrono::DateTime<chrono::Utc>>,
}
-impl From<Item> for ProjectItem {
- fn from(item: Item) -> Self {
- match item {
+impl ProjectItem {
+ fn from_item(item: Item) -> Option<Self> {
+ Some(match item {
Item::Document(document) => Self {
id: document.document_id,
item_type: ProjectItemType::Document,
@@ -53,13 +51,7 @@ impl From<Item> for ProjectItem {
file_type: document.file_type,
updated_at: document.updated_at,
},
- Item::Chat(chat) => Self {
- id: chat.id,
- item_type: ProjectItemType::Chat,
- name: chat.name,
- file_type: None,
- updated_at: chat.updated_at,
- },
+ Item::Chat(_) => return None,
Item::Project(project) => Self {
id: project.id,
item_type: ProjectItemType::Project,
@@ -67,7 +59,7 @@ impl From<Item> for ProjectItem {
file_type: None,
updated_at: project.updated_at,
},
- }
+ })
}
}
@@ -91,7 +83,7 @@ pub struct ReadProjectResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "ReadProject",
- description = "List the direct contents of a project (shown as a folder in the app UI): its documents, AI chats, and nested projects. Requires view access to the project. Email threads filed into the project are not included."
+ description = "List the direct contents of a project (shown as a folder in the app UI): its documents and nested projects. Requires view access to the project. Email threads filed into the project are not included."
)]
pub struct ReadProject {
/// The id of the project to read.
@@ -104,13 +96,11 @@ impl ToolAnnotated for ReadProject {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
- for ReadProject
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>> for ReadProject
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = ReadProjectResponse;
@@ -118,7 +108,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, project_id=?self.project_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
tracing::info!(params=?self, "Read project");
@@ -172,7 +162,7 @@ where
parent_project_id: project.parent_id,
items: items
.into_iter()
- .map(|item| ProjectItem::from(item.item))
+ .filter_map(|item| ProjectItem::from_item(item.item))
.collect(),
})
}
diff --git a/crates/projects/src/inbound/toolset/rename_item.rs b/crates/projects/src/inbound/toolset/rename_item.rs
index f2e2787b23..1953386789 100644
--- a/crates/projects/src/inbound/toolset/rename_item.rs
+++ b/crates/projects/src/inbound/toolset/rename_item.rs
@@ -1,4 +1,4 @@
-//! RenameItem tool for renaming projects (folders) and AI chats.
+//! RenameItem tool for renaming projects (folders).
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -10,7 +10,7 @@ use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use super::entity_receipts::{mutation_failed, user_receipt};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of item to rename.
#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
@@ -18,21 +18,17 @@ use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, Project
pub enum RenameableEntityType {
/// A project (folder).
Project,
- /// An AI chat conversation.
- Chat,
}
impl RenameableEntityType {
fn entity_type(self) -> EntityType {
match self {
Self::Project => EntityType::Project,
- Self::Chat => EntityType::Chat,
}
}
}
-const RENAME_FORBIDDEN: &str =
- "renaming a project requires edit access and renaming an AI chat requires owning it";
+const RENAME_FORBIDDEN: &str = "renaming a project requires edit access";
/// Rename an entity through its domain capability, as the user.
async fn rename_with<S, ESvc>(
@@ -72,7 +68,7 @@ pub struct RenameItemResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "RenameItem",
- description = "Rename a project (shown as a folder in the app) or an AI chat. Renaming a project requires edit access; renaming an AI chat requires owning it. Use RenameDocument for documents and tasks, and RenameChannel for channels."
+ description = "Rename a project (shown as a folder in the app). Renaming a project requires edit access. Use RenameDocument for documents and tasks, and RenameChannel for channels."
)]
pub struct RenameItem {
/// The kind of item to rename.
@@ -93,13 +89,11 @@ impl ToolAnnotated for RenameItem {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
- for RenameItem
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>> for RenameItem
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = RenameItemResponse;
@@ -107,7 +101,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, entity_type=?self.entity_type, entity_id=?self.entity_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
let name = self.name.trim().to_string();
@@ -133,16 +127,6 @@ where
)
.await?
}
- RenameableEntityType::Chat => {
- rename_with(
- &*service_context.chat_move_service,
- access,
- &request_context,
- entity,
- name.clone(),
- )
- .await?
- }
}
Ok(RenameItemResponse {
diff --git a/crates/projects/src/inbound/toolset/test.rs b/crates/projects/src/inbound/toolset/test.rs
index 6bd7f3e3ec..f087e07e66 100644
--- a/crates/projects/src/inbound/toolset/test.rs
+++ b/crates/projects/src/inbound/toolset/test.rs
@@ -53,7 +53,6 @@ fn test_move_to_project_schema_validation() {
fn test_move_to_project_deserializes_entity_types() {
for (raw, expected) in [
("document", MoveableEntityType::Document),
- ("chat", MoveableEntityType::Chat),
("email", MoveableEntityType::Email),
("project", MoveableEntityType::Project),
] {
@@ -139,7 +138,7 @@ fn test_update_sharing_maps_grants_to_levels() {
};
let tool = sharing(serde_json::json!({
- "entityType": "chat",
+ "entityType": "project",
"entityId": "d50676e2-0a12-4c62-bc07-4b1cb6d8e9bc",
"linkScope": "team",
"linkAccess": "comment",
diff --git a/crates/projects/src/inbound/toolset/update_sharing.rs b/crates/projects/src/inbound/toolset/update_sharing.rs
index 0ee2ba9daf..f4d2454628 100644
--- a/crates/projects/src/inbound/toolset/update_sharing.rs
+++ b/crates/projects/src/inbound/toolset/update_sharing.rs
@@ -1,5 +1,5 @@
//! UpdateSharing tool for changing link, team, and channel sharing on
-//! documents, AI chats, and projects.
+//! documents and projects.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -17,7 +17,7 @@ use serde::{Deserialize, Serialize};
use uuid::Uuid;
use super::entity_receipts::{mutation_failed, user_receipt};
-use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
+use super::{DocumentCapabilities, ProjectCapabilities, ProjectToolContext};
/// The kind of item whose sharing changes.
#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
@@ -25,8 +25,6 @@ use super::{ChatCapabilities, DocumentCapabilities, ProjectCapabilities, Project
pub enum SharingEntityType {
/// A document (includes tasks).
Document,
- /// An AI chat conversation.
- Chat,
/// A project (folder).
Project,
}
@@ -35,7 +33,6 @@ impl SharingEntityType {
fn entity_type(self) -> EntityType {
match self {
Self::Document => EntityType::Document,
- Self::Chat => EntityType::Chat,
Self::Project => EntityType::Project,
}
}
@@ -90,7 +87,7 @@ pub struct SharingChannel {
pub access: ShareAccess,
}
-const SHARE_FORBIDDEN: &str = "changing sharing requires edit access to a document and owning an AI chat or project; only the owner can change team access";
+const SHARE_FORBIDDEN: &str = "changing sharing requires edit access to a document and owning a project; only the owner can change team access";
/// Apply a share-policy update through the domain capability, as the user.
async fn share_with<S, ESvc>(
@@ -130,7 +127,7 @@ pub struct UpdateSharingResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "UpdateSharing",
- description = "Change who can access a document (including a task), an AI chat, or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning an AI chat or project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives)."
+ description = "Change who can access a document (including a task), or a project (folder), as the Share menu in the app does: link sharing, team access, and per-channel access. Each omitted field stays unchanged; off disables that share. Requires edit access to a document, or owning a project; only the owner can change team access. Use ShareWithChannel to post an item into a channel, and UpdateInitiativeSharing for Tasks projects (initiatives)."
)]
pub struct UpdateSharing {
/// The kind of item whose sharing changes.
@@ -204,13 +201,12 @@ impl ToolAnnotated for UpdateSharing {
}
#[async_trait]
-impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
+impl<PSvc, ESvc, DSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>
for UpdateSharing
where
PSvc: ProjectCapabilities,
ESvc: EntityAccessService,
DSvc: DocumentCapabilities,
- CSvc: ChatCapabilities,
EmSvc: MoveEntity + Send + Sync + 'static,
{
type Output = UpdateSharingResponse;
@@ -218,7 +214,7 @@ where
#[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, entity_type=?self.entity_type, entity_id=?self.entity_id), err)]
async fn call(
&self,
- service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>,
+ service_context: ServiceContext<ProjectToolContext<PSvc, ESvc, DSvc, EmSvc>>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
if self.is_empty() {
@@ -246,16 +242,6 @@ where
)
.await?
}
- SharingEntityType::Chat => {
- share_with(
- &*service_context.chat_move_service,
- access,
- &request_context,
- entity,
- policy,
- )
- .await?
- }
SharingEntityType::Project => {
share_with(
&*service_context.service,
diff --git a/crates/prompt/AGENTS.md b/crates/prompt/AGENTS.md
index d10f4443f8..11956d010c 100644
--- a/crates/prompt/AGENTS.md
+++ b/crates/prompt/AGENTS.md
@@ -34,6 +34,10 @@ AI system prompts: one module per prompt section, each exporting a
is long) exporting a `pub static PROMPT: StaticPrompt` → `pub mod` it in
`src/lib.rs` → compose it where the caller builds its prompt.
+## Tool contracts
+
+- Direct session-aware search/listing stays available in code mode; do not route conversation work to legacy chat tools or SDK namespaces.
+
## Checks
- `cargo test -p prompt` (`SQLX_OFFLINE` unset).
diff --git a/crates/prompt/src/about_macro.rs b/crates/prompt/src/about_macro.rs
index 0e3ac55e9f..f1476ac5f4 100644
--- a/crates/prompt/src/about_macro.rs
+++ b/crates/prompt/src/about_macro.rs
@@ -8,8 +8,8 @@ use crate::types::StaticPrompt;
static TITLE: &str = "About Macro";
-static INSTRUCTIONS: &str = r##"Macro is a single, fast workspace that unifies email, channels (messaging), chats
-(AI), tasks, docs, canvas, calls, CRM, and folders in one linked database.
+static INSTRUCTIONS: &str = r##"Macro is a single, fast workspace that unifies email, channels (messaging), agent sessions
+(AI conversations and coding), tasks, docs, canvas, calls, CRM, and folders in one linked database.
When a user asks an open-ended question about Macro itself — what it is, what it's
for, what it can do, or how to do something in Macro — call the SelfKnowledge tool.
@@ -31,12 +31,11 @@ When you open a pull request, open it ready for review, not as a draft, and get
## Terms
- Channel - a slack-like messaging channel
-- Chat - An AI conversation
+- Agent session - An AI conversation or coding session; inspect it with ReadAgentSession
- Email - Email messages
- Inbox - the "unified inbox", the user's workspace of recent items accessible via the ListEntities tool
-Be careful not to mix up chat and channels. Chat refers to AI chat's so it should only be used
-if a user is searching for seomething in a past AI conversation.
+Use agent-session search for past AI conversations. Channels contain messages between people.
Channels are the standard form of communication and should be prefered. If a user refers to "A message"
assume they mean a channel message.
@@ -50,8 +49,8 @@ tool — not their email inbox. Only treat "inbox" as the email inbox when the u
static INTENT: &str = "The model knows what Macro is at a high level, calls the SelfKnowledge \
tool for open-ended questions about Macro instead of guessing, disambiguates vague prompts like \
-\"what is this for?\", uses Macro terminology correctly: channels for messaging, chats only \
-for past AI conversations, and \"inbox\" as the unified inbox unless the user explicitly says email, \
+\"what is this for?\", uses Macro terminology correctly: channels for messaging, agent sessions \
+for AI conversations, and \"inbox\" as the unified inbox unless the user explicitly says email, \
and opens pull requests ready for review with CI passing rather than leaving them as drafts.";
/// The "About Macro" system prompt section.
diff --git a/crates/prompt/src/mentions.rs b/crates/prompt/src/mentions.rs
index 950ebacf52..57bc4c9584 100644
--- a/crates/prompt/src/mentions.rs
+++ b/crates/prompt/src/mentions.rs
@@ -22,7 +22,7 @@ static INSTRUCTIONS: &str = r##"These rules apply everywhere you author Markdown
When referencing a Macro item, person, date/time, agent session, or other mentionable chip, use XML mention tags with a JSON payload. Those tags render as clickable chips. Do not use plain Markdown links or bare names for these. Empty name/label strings are fine — the frontend resolves them.
-### Documents, channels, chats, and similar items
+### Documents, channels, and similar items
Use `<m-document-mention>` with the right `blockName` (and `blockParams` when needed):
@@ -30,7 +30,6 @@ Use `<m-document-mention>` with the right `blockName` (and `blockParams` when ne
- Image document mention (a generated or uploaded picture): `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"image","blockParams":{}}</m-document-mention>`
- Channel mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"channel","blockParams":{}}</m-document-mention>`
- Channel message mention: `<m-document-mention>{"documentId":"{channel_id}","documentName":"","blockName":"channel","blockParams":{"channel_message_id":"{message_id}"}}</m-document-mention>`
-- Chat mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"chat","blockParams":{}}</m-document-mention>`
- Project mention (a task project, i.e. an initiative): `<m-document-mention>{"documentId":"{initiative_id}","documentName":"","blockName":"initiative","blockParams":{}}</m-document-mention>`
- Folder mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"project","blockParams":{}}</m-document-mention>`
- Task mention: `<m-document-mention>{"documentId":"{id}","documentName":"","blockName":"task","blockParams":{}}</m-document-mention>`
diff --git a/crates/prompt/src/tool_usage.rs b/crates/prompt/src/tool_usage.rs
index 128f2b0896..59a00b3937 100644
--- a/crates/prompt/src/tool_usage.rs
+++ b/crates/prompt/src/tool_usage.rs
@@ -87,6 +87,6 @@ pub static CODE_MODE_ROUTING: StaticPrompt<'static> = StaticPrompt::borrowed(
"Code Mode Routing",
r#"Use ExecuteCode for SDK-supported listing, search, and retrieval, including a single precise call. This takes precedence over general references to direct tools elsewhere in these instructions. Consult DescribeCodeTools for the relevant SDK entity before falling back.
-For workspace activity, unified inbox, tasks, and mixed-entity feeds, use macro.workspace.page or macro.workspace.list with the requested type, time, tag, property, and mailbox filters. References to ListEntities elsewhere mean these SDK methods in this mode; the direct ListEntities tool is not available. ContentSearch remains available for session-history search or query scopes the SDK does not support. Preserve the user's source scope in either path. Keep EditDocument and other interactive or unsupported operations as direct tools."#,
+For workspace activity, unified inbox, tasks, and mixed-entity feeds, use the direct ListEntities tool with the requested type, time, tag, property, and mailbox filters. Use NameSearch for mixed-entity name searches. These tools include agent sessions. ContentSearch remains available for session-history search or query scopes the SDK does not support. Preserve the user's source scope in either path. Keep EditDocument and other interactive or unsupported operations as direct tools."#,
"SDK-supported retrieval uses code by default while unsupported scopes retain direct fallbacks.",
);
diff --git a/crates/properties/AGENTS.md b/crates/properties/AGENTS.md
index 6f550bf42c..b67a798497 100644
--- a/crates/properties/AGENTS.md
+++ b/crates/properties/AGENTS.md
@@ -43,6 +43,10 @@ events to the `macro.properties` Kafka topic.
`README.md`'s event table.
- Add a query: `src/outbound/<concern>_queries.rs` → its sibling `_test.rs`.
+## Tool contracts
+
+- AI property/tag adapters omit legacy chat targets; this does not change persisted property entity types.
+
## Checks
- `cargo test -p properties` (`SQLX_OFFLINE` unset; requires local MacroDB).
diff --git a/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs b/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
index 239fabefcd..8a997477f0 100644
--- a/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
+++ b/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
@@ -86,7 +86,6 @@ fn entity_type_label(entity_type: ToolPropertyTargetEntityType) -> &'static str
ToolPropertyTargetEntityType::Document => "document",
ToolPropertyTargetEntityType::Initiative => "initiative",
ToolPropertyTargetEntityType::Project => "project",
- ToolPropertyTargetEntityType::Chat => "chat",
ToolPropertyTargetEntityType::Thread => "thread",
ToolPropertyTargetEntityType::Channel => "channel",
ToolPropertyTargetEntityType::Call => "call",
diff --git a/crates/properties/src/inbound/toolset/create_tag.rs b/crates/properties/src/inbound/toolset/create_tag.rs
index 6ced4399e0..14138b4fc3 100644
--- a/crates/properties/src/inbound/toolset/create_tag.rs
+++ b/crates/properties/src/inbound/toolset/create_tag.rs
@@ -24,7 +24,7 @@ fn default_tag_scope() -> TagScope {
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(
title = "CreateTag",
- description = "Create a new tag — a colored label the user can apply to documents, emails, tasks, AI chats, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead."
+ description = "Create a new tag — a colored label the user can apply to documents, emails, tasks, and projects — in the user's personal set or their team's shared set. The set is provisioned automatically the first time a tag is created. Tags are matched by label, so call ListTags first and avoid creating one whose label duplicates an existing tag in the same set. Returns the new tag's id and its set's propertyDefinitionId, which you can pass straight to SetEntityProperty (add_option_ids) to apply the tag to an item. Use this only to create a brand-new tag; to apply an existing tag to an item, use ListTags then SetEntityProperty instead."
)]
#[serde(rename_all = "snake_case")]
pub struct CreateTag {
diff --git a/crates/properties/src/inbound/toolset/get_entity_properties.rs b/crates/properties/src/inbound/toolset/get_entity_properties.rs
index d1df449f84..da7424acab 100644
--- a/crates/properties/src/inbound/toolset/get_entity_properties.rs
+++ b/crates/properties/src/inbound/toolset/get_entity_properties.rs
@@ -25,7 +25,6 @@ pub enum ToolEntityType {
Task,
Initiative,
Project,
- Chat,
// Listing and search tools report email threads as `email`. A doc comment
// here would turn the schema enum into a named type, so this stays a plain
// comment.
@@ -45,7 +44,6 @@ impl From<ToolEntityType> for EntityType {
ToolEntityType::Task => EntityType::Task,
ToolEntityType::Initiative => EntityType::Initiative,
ToolEntityType::Project => EntityType::Project,
- ToolEntityType::Chat => EntityType::Chat,
ToolEntityType::Thread => EntityType::Thread,
ToolEntityType::Channel => EntityType::Channel,
ToolEntityType::Call => EntityType::CallRecord,
@@ -65,7 +63,6 @@ pub enum ToolPropertyTargetEntityType {
Document,
Initiative,
Project,
- Chat,
// Listing and search tools report email threads as `email`. A doc comment
// here would turn the schema enum into a named type, so this stays a plain
// comment.
@@ -83,7 +80,6 @@ impl From<ToolPropertyTargetEntityType> for model_entity::EntityType {
ToolPropertyTargetEntityType::Document => Self::Document,
ToolPropertyTargetEntityType::Initiative => Self::Initiative,
ToolPropertyTargetEntityType::Project => Self::Project,
- ToolPropertyTargetEntityType::Chat => Self::Chat,
ToolPropertyTargetEntityType::Thread => Self::EmailThread,
ToolPropertyTargetEntityType::Channel => Self::Channel,
ToolPropertyTargetEntityType::Call => Self::Call,
diff --git a/crates/soup/AGENTS.md b/crates/soup/AGENTS.md
index a1baf49b17..8c0ab2c2b3 100644
--- a/crates/soup/AGENTS.md
+++ b/crates/soup/AGENTS.md
@@ -50,6 +50,10 @@ rows, initiatives, ...) and get back a single unified, paginated result.
- Change what the work feed/Signal surfaces: `src/domain/service/tests/work_feed.rs`
→ `src/outbound/pg_soup_repo/work_feed.rs`.
+## Tool contracts
+
+- The AI `ListEntities` adapter includes agent sessions and excludes legacy chats; public feed contracts retain historical chat support.
+
## Checks
- `cargo test -p soup` (`SQLX_OFFLINE` unset; needs local MacroDB).
diff --git a/crates/soup/src/inbound/toolset/list_entities.rs b/crates/soup/src/inbound/toolset/list_entities.rs
index 2a02e7b852..f3356a5f4c 100644
--- a/crates/soup/src/inbound/toolset/list_entities.rs
+++ b/crates/soup/src/inbound/toolset/list_entities.rs
@@ -15,6 +15,7 @@ use item_filters::{
SharedEmailFilter,
ast::{
EntityFilterAst, LiteralTree,
+ agent_session::AgentSessionLiteral,
calendar_event::CalendarEventLiteral,
call::CallLiteral,
channel::{ChannelLiteral, ChannelThreadLiteral},
@@ -94,8 +95,8 @@ pub enum ItemType {
CalendarEvent,
/// Macro document.
Document,
- /// AI chat conversation.
- AiChat,
+ /// Agent session conversation.
+ AgentSession,
/// Macro project.
Project,
/// Email thread.
@@ -153,16 +154,25 @@ pub enum EntityItem {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
tags: Vec<AppliedTag>,
},
- /// AI chat item.
+ /// Agent session, including its current runtime state.
#[serde(rename_all = "camelCase")]
- AiChat {
- /// Chat id.
+ AgentSession {
+ /// Session id for ReadAgentSession and session actions.
id: Uuid,
- /// Chat name.
+ /// Session title.
name: String,
- /// Tags on the chat visible to the user.
- #[serde(default, skip_serializing_if = "Vec::is_empty")]
- tags: Vec<AppliedTag>,
+ /// Owner's principal id.
+ owner_id: String,
+ /// Agent persona id.
+ bot_id: Uuid,
+ /// Whether the session is archived.
+ is_archived: bool,
+ /// Runtime connection status.
+ status: String,
+ /// Latest turn state, when available.
+ turn_state: Option<String>,
+ /// Selected repository, when present.
+ repo_url: Option<String>,
},
/// Project item.
#[serde(rename_all = "camelCase")]
@@ -270,10 +280,15 @@ impl EntityItem {
name: doc.name,
tags: resolve_applied_tags(&doc.extra.properties, tag_map),
},
- SoupItem::Chat(chat) => EntityItem::AiChat {
- id: chat.id,
- name: chat.name,
- tags: resolve_applied_tags(&chat.extra.properties, tag_map),
+ SoupItem::AgentSession(session) => EntityItem::AgentSession {
+ id: session.id,
+ name: session.name,
+ owner_id: session.owner_id.to_string(),
+ bot_id: session.bot_id,
+ is_archived: session.is_archived,
+ status: session.status,
+ turn_state: session.turn_state,
+ repo_url: session.repo_url,
},
SoupItem::Project(project) => EntityItem::Project {
id: project.id,
@@ -312,9 +327,7 @@ impl EntityItem {
SoupItem::Initiative(_) => {
unreachable!("ListEntities tool does not surface Initiative rows")
}
- SoupItem::AgentSession(_) => {
- unreachable!("ListEntities tool does not surface AgentSession rows")
- }
+ SoupItem::Chat(_) => unreachable!("legacy chats are excluded from agent tools"),
SoupItem::DatabaseRow(_) => {
unreachable!("ListEntities tool does not surface DatabaseRow rows")
}
@@ -393,7 +406,7 @@ pub struct ListEntitiesResponse {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "ListEntities",
- description = "Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as \"list my tasks\", \"tasks assigned to me\", or \"tasks I completed yesterday\", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {\"l\":{\"dst\":\"task\"}} and includeTypes [\"document\"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For \"completed yesterday\", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. \"my items tagged bug-report\"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead."
+ description = "Browse the user's Macro workspace to see recent items they have access to. Returns Macro documents, agent sessions, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as \"what happened today\", \"what's going on\", \"catch me up\", or \"what happened in standup today\"; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as \"list my tasks\", \"tasks assigned to me\", or \"tasks I completed yesterday\", prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {\"l\":{\"dst\":\"task\"}} and includeTypes [\"document\"]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user's assignee entity id is their Macro user id, usually macro|<their email address from context>. For \"completed yesterday\", combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. \"my items tagged bug-report\"), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead."
)]
pub struct ListEntities {
/// Filter returned items to specific item types.
@@ -433,13 +446,13 @@ pub struct ListEntities {
#[serde(default, rename = "pf")]
pub project_filter: LiteralTree<ProjectLiteral>,
- /// AI chat entity AST filter.
+ /// Agent-session AST filter; omit to include accessible standalone sessions.
#[schemars(
- description = "Full soup AST AI chat filter (cf).",
+ description = "Agent-session filter (asf): use {\"l\":{\"id\":\"<session UUID>\"}} for a session, or {\"l\":{\"o\":\"macro|[email protected]\"}} for an owner.",
with = "Option<serde_json::Value>"
)]
- #[serde(default, rename = "cf")]
- pub chat_filter: LiteralTree<ChatLiteral>,
+ #[serde(default, rename = "asf")]
+ pub agent_session_filter: LiteralTree<AgentSessionLiteral>,
/// High-level email filter preset.
#[schemars(
@@ -524,7 +537,7 @@ with tagsMatch=\"all\". Each entry names a tag by its label, matched case-insens
against the user's own tags; only set scope (\"personal\" or \"team\") when the user \
distinguishes between their personal and team tags. An unknown label fails with the list of \
available tags — call ListTags first when unsure what tags exist. Only taggable items \
-(documents, tasks, projects, emails, AI chats, call records) can match a tag filter. Prefer \
+(documents, tasks, projects, emails, call records) can match a tag filter. Prefer \
this over hand-building a propf filter for tags.")]
#[serde(default)]
pub tags: Option<Vec<TagFilter>>,
@@ -562,7 +575,7 @@ impl ListEntities {
calendar_event_filter: None,
document_filter: self.document_filter.clone(),
project_filter: self.project_filter.clone(),
- chat_filter: self.chat_filter.clone(),
+ chat_filter: Some(Arc::new(Expr::val(ChatLiteral::ChatId(Uuid::nil())))),
// Toolset doesn't (yet) expose CRM scope; the tool surface stays
// per-link unless we add explicit fields for it.
email_filter: item_filters::ast::EmailFilterAst {
@@ -581,8 +594,10 @@ impl ListEntities {
crm_contact_filter: None,
foreign_entity_filter: self.foreign_entity_filter.clone(),
github_pull_request_filter: None,
- // Agent sessions are opt-in too; unset keeps them off the tool surface.
- agent_session_filter: None,
+ agent_session_filter: self
+ .agent_session_filter
+ .clone()
+ .or_else(|| Some(Arc::new(Expr::val(AgentSessionLiteral::Include)))),
initiative_filter: None,
// Database rows are opt-in as well; the tool never names a table.
database_row_filter: None,
@@ -622,11 +637,7 @@ impl ListEntities {
} else {
Some(Arc::new(Expr::val(ProjectLiteral::ProjectId(Uuid::nil()))))
},
- chat_filter: if include_types.contains(&ItemType::AiChat) {
- ast.chat_filter
- } else {
- Some(Arc::new(Expr::val(ChatLiteral::ChatId(Uuid::nil()))))
- },
+ chat_filter: ast.chat_filter,
email_filter: if include_types.contains(&ItemType::Email) {
ast.email_filter
} else {
@@ -662,7 +673,11 @@ impl ListEntities {
Some(Arc::new(Expr::val(ForeignEntityLiteral::Id(Uuid::nil()))))
},
github_pull_request_filter: None,
- agent_session_filter: ast.agent_session_filter,
+ agent_session_filter: if include_types.contains(&ItemType::AgentSession) {
+ ast.agent_session_filter
+ } else {
+ None
+ },
initiative_filter: None,
database_row_filter: None,
properties_filter: ast.properties_filter,
@@ -825,14 +840,12 @@ where
.map(|sets| sets.applied_tag_by_option_id())
.unwrap_or_default();
- let mut items: Vec<EntityItem> = paginated
+ let items: Vec<EntityItem> = paginated
.items
.into_iter()
.map(|EnrichedSoupItem { item, .. }| EntityItem::from_soup_item(item, &tag_map))
.collect();
- retain_excluding_self_chat(&mut items, service_context.self_chat_id);
-
// Build summary
let summary = build_summary(&items, has_more, &self.effective_include_types());
@@ -840,15 +853,6 @@ where
}
}
-/// Drop the chat the agent is currently running inside from `items` so it
-/// never surfaces itself in its own results.
-pub(super) fn retain_excluding_self_chat(items: &mut Vec<EntityItem>, self_chat_id: Option<Uuid>) {
- let Some(self_chat_id) = self_chat_id else {
- return;
- };
- items.retain(|item| !matches!(item, EntityItem::AiChat { id, .. } if *id == self_chat_id));
-}
-
async fn fetch_caller_tag_sets<T, E>(
service_context: &ServiceContext<SoupToolContext<T, E>>,
request_context: &RequestContext,
@@ -884,7 +888,7 @@ pub(super) fn build_summary(
// Count by type
let mut docs = 0;
- let mut chats = 0;
+ let mut sessions = 0;
let mut projects = 0;
let mut emails = 0;
let mut channels = 0;
@@ -896,7 +900,7 @@ pub(super) fn build_summary(
for item in items {
match item {
EntityItem::Document { .. } => docs += 1,
- EntityItem::AiChat { .. } => chats += 1,
+ EntityItem::AgentSession { .. } => sessions += 1,
EntityItem::Project { .. } => projects += 1,
EntityItem::Email { .. } => emails += 1,
EntityItem::Channel { .. } => channels += 1,
@@ -914,10 +918,10 @@ pub(super) fn build_summary(
if docs == 1 { "" } else { "s" }
));
}
- if chats > 0 {
+ if sessions > 0 {
parts.push(format!(
- "{chats} AI conversation{}",
- if chats == 1 { "" } else { "s" }
+ "{sessions} agent session{}",
+ if sessions == 1 { "" } else { "s" }
));
}
if projects > 0 {
diff --git a/crates/soup/src/inbound/toolset/test.rs b/crates/soup/src/inbound/toolset/test.rs
index 6e94e86f8e..26292c7aab 100644
--- a/crates/soup/src/inbound/toolset/test.rs
+++ b/crates/soup/src/inbound/toolset/test.rs
@@ -1,4 +1,4 @@
-use super::list_entities::{build_summary, retain_excluding_self_chat};
+use super::list_entities::build_summary;
#[allow(unused_imports)]
use super::*;
use ai_toolset::schema::generate_validated_input_schema;
@@ -482,59 +482,37 @@ fn test_from_soup_item_resolves_tags_via_caller_map() {
}
#[test]
-fn test_retain_excluding_self_chat_drops_only_the_current_chat() {
- let self_chat_id = Uuid::new_v4();
- let other_chat_id = Uuid::new_v4();
- let mut items = vec![
- EntityItem::AiChat {
- id: self_chat_id,
- name: "Current chat".to_string(),
- tags: vec![],
- },
- EntityItem::AiChat {
- id: other_chat_id,
- name: "Other chat".to_string(),
- tags: vec![],
- },
- EntityItem::Document {
- id: Uuid::new_v4(),
- name: "doc.md".to_string(),
- file_type: None,
- sub_type: None,
- tags: vec![],
- },
- ];
-
- retain_excluding_self_chat(&mut items, Some(self_chat_id));
-
- assert_eq!(items.len(), 2, "the current chat should be dropped");
+fn agent_listing_includes_sessions_and_excludes_legacy_chats() {
+ let ast = ListEntities::default().entity_filter_ast(None);
+ assert_eq!(
+ serde_json::to_value(ast.chat_filter).unwrap(),
+ serde_json::json!({"l":{"cid":Uuid::nil()}})
+ );
+ assert_eq!(
+ serde_json::to_value(ast.agent_session_filter).unwrap(),
+ serde_json::json!({"l":"inc"})
+ );
+ let only_sessions: ListEntities = serde_json::from_value(serde_json::json!({"includeTypes":["agent_session"], "asf":{"l":{"id":"0195ceb6-ec2e-7023-80e4-6e084fa6cccd"}}})).unwrap();
+ let ast = only_sessions.entity_filter_ast(None);
+ assert_eq!(
+ serde_json::to_value(ast.agent_session_filter).unwrap(),
+ serde_json::json!({"l":{"id":"0195ceb6-ec2e-7023-80e4-6e084fa6cccd"}})
+ );
+ assert!(ast.document_filter.is_some());
+ let documents: ListEntities =
+ serde_json::from_value(serde_json::json!({"includeTypes":["document"]})).unwrap();
assert!(
- items
- .iter()
- .any(|item| matches!(item, EntityItem::AiChat { id, .. } if *id == other_chat_id)),
- "unrelated chats should be kept"
+ documents
+ .entity_filter_ast(None)
+ .agent_session_filter
+ .is_none()
);
assert!(
- items
- .iter()
- .any(|item| matches!(item, EntityItem::Document { .. })),
- "non-chat items should be kept"
+ serde_json::from_value::<ListEntities>(serde_json::json!({"includeTypes":["ai_chat"]}))
+ .is_err()
);
}
-#[test]
-fn test_retain_excluding_self_chat_is_noop_without_a_running_chat() {
- let mut items = vec![EntityItem::AiChat {
- id: Uuid::new_v4(),
- name: "Some chat".to_string(),
- tags: vec![],
- }];
-
- retain_excluding_self_chat(&mut items, None);
-
- assert_eq!(items.len(), 1, "nothing to exclude outside a chat session");
-}
-
// run `cargo test -p soup inbound::toolset::test::print_input_schema -- --nocapture --include-ignored`
#[test]
#[ignore = "prints the input schema"]
diff --git a/docs/agent-guide/ai-chat.md b/docs/agent-guide/ai-chat.md
index 3e4913fead..f62d1adb98 100644
--- a/docs/agent-guide/ai-chat.md
+++ b/docs/agent-guide/ai-chat.md
@@ -811,11 +811,10 @@ For Macro's in-process agent, the backend evaluates the session owner's
`ai-code-mode` flag once per conversational turn. Enabled users get a smaller
direct toolset: SDK-supported searches, reads, listing, and data operations run
through the SDK. Document editing keeps the direct `EditDocument` tool, and
-`DisplayResults` remains available for rendering results. Workspace feeds use
-`macro.workspace.page` or the lazy `macro.workspace.list` iterator with type,
-time, tag, property, and mailbox filters. Direct `ListEntities` is absent even
-from lazy discovery; `ContentSearch` remains for query scopes not supported by
-SDK search, such as session history. Methods
+`DisplayResults` remains available for rendering results. Workspace feeds and
+mixed-entity name searches keep the direct `ListEntities` and `NameSearch` tools,
+including agent sessions. `ContentSearch` supports session history. The legacy
+chat and workspace SDK namespaces are excluded from agent documentation. Methods
routed through the SDK are absent from direct schemas, `SearchTools`, and `LoadTools`;
they remain discoverable through `DescribeCodeTools`. User-review
tools, `AskUser`, connector discovery, tool loading for connected apps, subagents,
@@ -834,10 +833,9 @@ automatic retry through a direct tool.
Ask the agent to discover SDK entities and write a JavaScript module exporting
`async function main({macro, session, execution})`. These are actual public SDK
handles; for example, `macro.documents.search(...)` is an async iterator and
-`await document.content()` fetches a document. `macro.workspace.list(...)` browses
-workspace entities with type, time, task, tag, mailbox, and sorting filters;
-`macro.workspace.page(...)` exposes an explicit page and continuation cursor.
-The direct `ListEntities` tool is absent for code-mode users. Return plain JSON
+`await document.content()` fetches a document. Use the direct `ListEntities` tool
+for workspace feeds with type, time, task, tag, mailbox, and sorting filters.
+Return plain JSON
in `{data}`. The optional `reviews` array contains saved review references and
defaults to `[]` when omitted. Loops, early breaks and bounded parallel
promises are supported. Preserve the user's source filters, source IDs, errors,
@@ -1966,3 +1964,31 @@ New conversations confirm selected model and effort settings before sending the
first message. If startup reports a rejected setting or timeout, the first prompt
has not been sent. See [effort capabilities](../architecture/agent-effort.md) for the harness
contracts and test coverage.
+
+### Read another agent session
+
+An agent-session mention or search result supplies the ID for `ReadAgentSession`.
+The tool requires the viewer's normal session access and returns the latest 20
+folded messages, including prompts, replies, tool activity, and failures. Pass a
+returned turn number to read that turn instead. Messages are capped at 4000
+characters; response and message truncation flags identify omissions. Terminal
+failures are returned separately so long replies cannot hide them. The tool
+row expands to show the returned conversation, runtime status, and archive state
+on desktop and mobile. Legacy chat tools are absent from agent context; saved
+legacy tool calls still render in historical conversations.
+
+Use `ListEntities` with `includeTypes: ["agent_session"]`, `NameSearch`, or
+`ContentSearch` to find sessions. `ListAgents` identifies available agents and
+`CreateAgentSession` starts a conversation with the chosen agent. Use
+`ManageAgentSession` to rename, archive/unarchive, delete, prompt, or stop one.
+Rename, archive, and delete require ownership; prompt and stop require edit
+access. Prompt acceptance reports sent or queued, not completion. An uncertain
+result must be checked by reading the session before retrying.
+
+`ReadAgentSessionSharing` shows link, team, and channel grants;
+`UpdateAgentSessionSharing` changes grants as the owner. Private persona
+conversations retain their existing sharing restrictions. `ShareWithChannel`
+can share a session into a channel. These tools cannot approve permission
+requests on a user's behalf.
+
+![Expanded session read with a terminal failure visible after truncated text](media/ai-chat/read-agent-session.png)
diff --git a/docs/agent-guide/media/ai-chat/read-agent-session.png b/docs/agent-guide/media/ai-chat/read-agent-session.png
new file mode 100644
index 0000000000..e48e55b470
Binary files /dev/null and b/docs/agent-guide/media/ai-chat/read-agent-session.png differ
diff --git a/docs/development/rust.md b/docs/development/rust.md
index 5b345ef51b..91cabddd67 100644
--- a/docs/development/rust.md
+++ b/docs/development/rust.md
@@ -68,6 +68,10 @@ query metadata. If a test reports missing SQLx cache data, follow the
[database troubleshooting workflow](database.md#troubleshooting);
do not enable offline mode to work around it.
+CI limits Cargo to two concurrent build jobs for tests because linking several
+large service test binaries can exhaust runner memory. Nextest's test worker
+count is configured separately; the build limit does not reduce test coverage.
+
Keep tests in a sibling `test.rs` (CS-49). For example, `src/user.rs` declares:
```rust
diff --git a/packages/code-mode-sdk/AGENTS.md b/packages/code-mode-sdk/AGENTS.md
index a867200db2..3e1976e33d 100644
--- a/packages/code-mode-sdk/AGENTS.md
+++ b/packages/code-mode-sdk/AGENTS.md
@@ -14,6 +14,10 @@ HTML worker belong to `packages/sdk-docs`.
a topic so discovery stays within its 32-question classifier limit.
- `src/index.ts`: public SDK exports used by programs.
+## Tool contracts
+
+- Agent documentation excludes the legacy chats/workspace namespaces and their Macro properties; public SDK APIs remain compatible for existing callers.
+
## Checks
- `bun run generate`, then `bun run check:generated`.
diff --git a/packages/code-mode-sdk/scripts/catalog.ts b/packages/code-mode-sdk/scripts/catalog.ts
index 9a62696811..0780793d55 100644
--- a/packages/code-mode-sdk/scripts/catalog.ts
+++ b/packages/code-mode-sdk/scripts/catalog.ts
@@ -18,7 +18,6 @@ export const descriptions: Record<string, string> = {
calendar: 'Find and manage calendar events.',
calls: 'Read and edit call records, transcripts and meeting links.',
channels: 'Read and send channel messages.',
- chats: 'Read and send AI chat messages and stop generations.',
crm: 'Work with CRM records and pipeline tables, columns, rows and sharing.',
databases: 'Read and edit database schemas, rows, and cells.',
documents: 'Search, read, create, and manage documents and tasks.',
@@ -34,6 +33,4 @@ export const descriptions: Record<string, string> = {
teams: 'Manage teams and membership.',
users: 'Look up users and their profiles.',
webhooks: 'Manage API webhook subscriptions.',
- workspace:
- 'Browse recent workspace entities across documents, tasks, email, calendars, channels, calls, projects and chats with time, property, tag and inbox filters.',
};
diff --git a/packages/code-mode-sdk/scripts/typedoc.ts b/packages/code-mode-sdk/scripts/typedoc.ts
index 9f56fa84df..56869a83bd 100644
--- a/packages/code-mode-sdk/scripts/typedoc.ts
+++ b/packages/code-mode-sdk/scripts/typedoc.ts
@@ -16,9 +16,26 @@ export async function readMarkdownPages(directory: string) {
}
export function packageEntityDocs(
- pages: ReadonlyMap<string, string>,
+ sourcePages: ReadonlyMap<string, string>,
descriptions: Readonly<Record<string, string>>
) {
+ // The public SDK retains deployed legacy APIs. Native discovery tools cover
+ // current sessions; omit the legacy chat and workspace namespaces here.
+ const hiddenNamespace = (path: string) =>
+ /^src\/entities\/(chats|workspace)\//.test(path);
+ const pages = new Map(
+ [...sourcePages]
+ .filter(([path]) => !hiddenNamespace(path))
+ .map(([path, markdown]) => [
+ path,
+ markdown
+ .replace(
+ /^### (?:chats|workspace)\b[^\n]*\n[\s\S]*?(?=^### |(?![\s\S]))/gm,
+ ''
+ )
+ .replace(/^\| <a id="property-(?:chats|workspace)"[^\n]*\n/gm, ''),
+ ])
+ );
const core = [
'src/macro/',
'src/config/',
@@ -74,6 +91,7 @@ export function packageEntityDocs(
const target = posix.normalize(
posix.join(posix.dirname(path), decodeURIComponent(match[1] ?? ''))
);
+ if (hiddenNamespace(target)) continue;
if (!pages.has(target))
throw new Error(`Broken TypeDoc link: ${path} -> ${target}`);
if (target.startsWith('generated/')) included.add(target);
diff --git a/packages/code-mode-sdk/src/documentation.test.ts b/packages/code-mode-sdk/src/documentation.test.ts
index 00edeb6a1a..6529f40499 100644
--- a/packages/code-mode-sdk/src/documentation.test.ts
+++ b/packages/code-mode-sdk/src/documentation.test.ts
@@ -35,6 +35,21 @@ describe('TypeDoc documentation packaging', () => {
expect(entity?.overview).not.toContain('# Child');
});
+ it('omits legacy namespaces without removing adjacent current session methods', () => {
+ const pages = fixturePages();
+ pages.set(
+ 'src/macro/classes/Macro.md',
+ '# Macro\n### chats\n[Chats](../../entities/chats/namespace/classes/Chats.md)\n### agentSessions\nCurrent sessions\n### workspace\nLegacy feed'
+ );
+ const docs = packageEntityDocs(pages, { example: 'An example.' });
+ const core = docs.find((doc) => doc.name === 'core');
+ expect(core?.documentation).toContain(
+ '### agentSessions\nCurrent sessions'
+ );
+ expect(core?.documentation).not.toContain('### chats');
+ expect(core?.documentation).not.toContain('Legacy feed');
+ });
+
it('fails generation on a missing referenced contract or missing namespace', () => {
const pages = fixturePages();
pages.delete('generated/example/types.gen/type-aliases/Child.md');
@@ -107,15 +122,14 @@ describe('TypeDoc documentation packaging', () => {
expect(
docs.find((doc) => doc.name === 'documents')?.documentation
).toContain('content()');
- const workspace = docs.find((doc) => doc.name === 'workspace');
- expect(workspace?.documentation).toContain('WorkspaceNamespace');
- expect(workspace?.documentation).toContain('WorkspacePageOptions');
- expect(workspace?.documentation).toContain('ApiEntityFilterAst');
- expect(workspace?.overview).toContain('page()');
- expect(workspace?.overview).toContain('list()');
- expect(workspace?.overview).toContain('# Type Alias: WorkspaceType');
- expect(workspace?.overview).toContain('calendar_event');
- expect(workspace?.overview).toContain('ai_chat');
+ expect(docs.some((doc) => ['chats', 'workspace'].includes(doc.name))).toBe(
+ false
+ );
+ const core = docs.find((doc) => doc.name === 'core');
+ expect(core?.documentation).not.toMatch(/^### (chats|workspace)\b/m);
+ expect(core?.documentation).toContain('`agentSessions`');
+ expect(core?.documentation).not.toContain('property-chats');
+ expect(core?.documentation).not.toContain('property-workspace');
expect(docs.length).toBeLessThanOrEqual(32);
expect(
docs.find((doc) => doc.name === 'routines')?.documentation
diff --git a/services/agent_harness_service/AGENTS.md b/services/agent_harness_service/AGENTS.md
index 6cceb9310e..533e39bd2e 100644
--- a/services/agent_harness_service/AGENTS.md
+++ b/services/agent_harness_service/AGENTS.md
@@ -38,6 +38,10 @@ sessions: agent-session trigger events in, sandboxed coding agent sessions
`src/model_providers/mod.rs` → wire into `src/main.rs`.
- Inspect a session's protocol log: `just session-log <channel_id>`.
+## Tool contracts
+
+- Internal session tools require a verified acting user plus owner/edit authorization. Keep their restricted prompt/stop route separate from human approval controls.
+
## Checks
- `cargo test -p agent_harness_service` (`SQLX_OFFLINE` unset).
diff --git a/services/agent_harness_service/src/api.rs b/services/agent_harness_service/src/api.rs
index 60a6f334ba..42d81e49a7 100644
--- a/services/agent_harness_service/src/api.rs
+++ b/services/agent_harness_service/src/api.rs
@@ -263,6 +263,10 @@ where
Models: AgentModelsService,
Changes: AgentChanges,
{
+ let tool_actions =
+ agent_session::inbound::axum_router::tool_actions::agent_session_tool_actions_router(
+ states.control.clone(),
+ );
let agent_sessions = agent_session_read_router(states.read.clone())
.merge(agent_session_control_router(states.control))
.merge(agent_session_create_router(states.create))
@@ -273,6 +277,7 @@ where
.merge(agent_changes_router(states.changes));
Router::new()
.nest("/agent-sessions", agent_sessions)
+ .merge(tool_actions)
.merge(agent_sandbox_size_router(states.read.clone()))
.merge(agent_coding_preferences_router(states.read))
.merge(agent_models_router(states.models))
diff --git a/services/agent_harness_service/src/api/test.rs b/services/agent_harness_service/src/api/test.rs
index 97dde8256d..75360884fc 100644
--- a/services/agent_harness_service/src/api/test.rs
+++ b/services/agent_harness_service/src/api/test.rs
@@ -330,6 +330,14 @@ async fn gateway_egress_keeps_authentication_and_git_basic_challenge() {
}
impl CodingAgentService for RoutineSessionsSpy {
+ fn create(
+ &self,
+ command: DispatchCodingAgentRequest,
+ ) -> Pin<Box<dyn Future<Output = Result<DispatchedCodingAgent, CodingAgentError>> + Send + '_>>
+ {
+ self.dispatch(command)
+ }
+
fn list(
&self,
user_id: macro_user_id::user_id::MacroUserIdStr<'static>,
diff --git a/services/document_cognition_service/src/api/context/test.rs b/services/document_cognition_service/src/api/context/test.rs
index 883df54f11..9cb1dcc153 100644
--- a/services/document_cognition_service/src/api/context/test.rs
+++ b/services/document_cognition_service/src/api/context/test.rs
@@ -443,7 +443,6 @@ pub async fn test_api_context(pool: sqlx::Pool<sqlx::Postgres>) -> std::sync::Ar
macro_event_broker.clone(),
entity_access_service.clone(),
document_tool_context.service.clone(),
- chat_tool_context.service.clone(),
user_email_service.clone(),
);
@@ -554,6 +553,10 @@ pub async fn test_api_context(pool: sqlx::Pool<sqlx::Postgres>) -> std::sync::Ar
"http://localhost:8086".to_string(),
None,
),
+ read_agent_session_context: ai_tools::build_read_agent_session_context(
+ pool.clone(),
+ entity_access_service.clone(),
+ ),
coding_agent_tool_context: ai_tools::build_coding_agent_tool_context(
macro_service_urls::ServiceUrl::owned("http://localhost:0").into(),
"test-internal-api-key".to_string(),
diff --git a/services/document_cognition_service/src/server.rs b/services/document_cognition_service/src/server.rs
index 3c9366cc06..d90e70c8e4 100644
--- a/services/document_cognition_service/src/server.rs
+++ b/services/document_cognition_service/src/server.rs
@@ -694,7 +694,6 @@ pub async fn run() -> anyhow::Result<()> {
macro_event_broker.clone(),
entity_access_service.clone(),
document_tool_context.service.clone(),
- chat_tool_context.service.clone(),
user_email_service.clone(),
);
@@ -809,6 +808,10 @@ pub async fn run() -> anyhow::Result<()> {
DocumentStorageServiceUrl::new()?.to_string(),
pipedream_client.clone(),
),
+ read_agent_session_context: ai_tools::build_read_agent_session_context(
+ db.clone(),
+ entity_access_service.clone(),
+ ),
coding_agent_tool_context: ai_tools::build_coding_agent_tool_context(
macro_service_urls::AgentHarnessServiceUrl::new()?,
internal_api_key.clone(),
diff --git a/services/mcp_service/AGENTS.md b/services/mcp_service/AGENTS.md
index 5bab282abb..ff9625d1c0 100644
--- a/services/mcp_service/AGENTS.md
+++ b/services/mcp_service/AGENTS.md
@@ -38,15 +38,20 @@ FusionAuth.
## Recipes
-- Add an MCP tool: implement it in `crates/ai_toolset` (shared with chat) →
- no changes usually needed here unless the tool needs MCP-specific response
- shaping → `src/tool_response.rs` / `src/markdown_images.rs`.
+- Add an MCP tool: implement it in the owning domain's `inbound::toolset` →
+ register it in `crates/ai_tools` (shared with chat) → wire any new context
+ in `src/context.rs`. MCP-specific response shaping lives in
+ `src/tool_response.rs` / `src/markdown_images.rs`.
- Add a config value: `src/config.rs` → Doppler → the `mcp_service_doppler_config`
binary validates it in CI.
- Allow a new MCP client origin: `src/config.rs`
(`DEFAULT_MCP_ALLOWED_REDIRECT_HOSTS`) — see `mcp_auth_proxy/README.md` for
the redirect URI policy this feeds.
+## Tool contracts
+
+- Agent sessions use the shared session toolset; legacy chat tools are not advertised or callable.
+
## Checks
- `cargo test -p mcp_service` (`SQLX_OFFLINE` unset).
diff --git a/services/mcp_service/src/context.rs b/services/mcp_service/src/context.rs
index c5abf86f9a..c78212647a 100644
--- a/services/mcp_service/src/context.rs
+++ b/services/mcp_service/src/context.rs
@@ -408,7 +408,6 @@ async fn build_tool_context(args: ToolContextBuildArgs<'_>) -> anyhow::Result<To
macro_event_broker.clone(),
entity_access_service.clone(),
document_tool_context.service.clone(),
- chat_tool_context.service.clone(),
user_email_service.clone(),
);
@@ -591,6 +590,10 @@ async fn build_tool_context(args: ToolContextBuildArgs<'_>) -> anyhow::Result<To
dss_url,
pipedream_client,
),
+ read_agent_session_context: ai_tools::build_read_agent_session_context(
+ db.clone(),
+ entity_access_service.clone(),
+ ),
coding_agent_tool_context: ai_tools::build_coding_agent_tool_context(
macro_service_urls::AgentHarnessServiceUrl::new()?,
config.internal_api_key.to_string(),
diff --git a/services/mcp_service/src/tool_service.rs b/services/mcp_service/src/tool_service.rs
index 6c93f15c3b..ad6a04fddf 100644
--- a/services/mcp_service/src/tool_service.rs
+++ b/services/mcp_service/src/tool_service.rs
@@ -113,7 +113,7 @@ where
info.instructions = Some(format!(
"This server provides tools for interacting with a user's Macro workspace. \
Use ContentSearch and NameSearch to find entities. \
- Use ReadContent, ReadMetadata, and ReadThread to read them. \
+ Use ReadContent and ReadMetadata for documents, ReadAgentSession for agent-session conversations. \
Use ReadChannelMessages, ReadChannelThread, and ReadChannelMessageContext \
to read channel messages and their attachments. Channel image attachments \
include inline images when available; image and video attachments include \
diff --git a/services/mcp_service/src/tool_service/test.rs b/services/mcp_service/src/tool_service/test.rs
index 5c174a9357..6367d6c75e 100644
--- a/services/mcp_service/src/tool_service/test.rs
+++ b/services/mcp_service/src/tool_service/test.rs
@@ -58,7 +58,7 @@ async fn server_instructions_describe_available_workflows() {
"NameSearch",
"ReadContent",
"ReadMetadata",
- "ReadThread",
+ "ReadAgentSession",
"ReadChannelMessages",
"ReadChannelThread",
"ReadChannelMessageContext",
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs
index 23ea769b83..956d2c92cc 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/code_check_cloud_storage.rs
@@ -158,6 +158,7 @@ fn test() -> Job {
"${{ needs.path-check.outputs.rust_packages }}",
))
.add_env(("NEXTEST_TEST_THREADS", vars::NEXTEST_TEST_THREADS))
+ .add_env(("CARGO_BUILD_JOBS", vars::RUST_TEST_BUILD_JOBS))
.add_env(("RUSTFLAGS", "-Dwarnings -C link-arg=-fuse-ld=mold"))
// The default 10-minute idle timeout can stop the server during long
// link or test phases, which resets the stats reported at the end.
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/vars.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/vars.rs
index b4bf6d2740..6455bc17b6 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/vars.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/vars.rs
@@ -46,6 +46,9 @@ pub const NIX_CACHE_URL: &str = "${{ vars.NIX_CACHE_URL }}";
/// paths verify.
pub const NIX_CACHE_PUBLIC_KEY: &str = "${{ vars.NIX_CACHE_PUBLIC_KEY }}";
+/// Limit concurrent test links, which can each consume several GiB.
+pub const RUST_TEST_BUILD_JOBS: u32 = 2;
+
/// Nextest thread count for the test job. Tuned for the previous
/// `linux-extra-beefy` runner; revisit if `namespace-profile-linux-mid` is
/// smaller.