@mindstudio-ai/agent 0.1.111 → 0.1.113

package/dist/index.d.ts

@@ -3276,6 +3276,58 @@ interface Email {
     unsuppress(email: string): Promise<UnsuppressResult>;
 }
 
+interface EventGrantOptions {
+    /**
+     * Grant lifetime in seconds — also the stream lifetime and the
+     * authorization staleness budget. The platform clamps to [60, 3600]
+     * (default 900): at expiry the stream closes and the client re-mints
+     * through your method, which re-runs your checks. A user whose access you
+     * revoke keeps receiving for at most this long.
+     */
+    ttlSeconds?: number;
+}
+interface EventGrantResult {
+    /** Bearer token for `GET /_/events` (`Accept: text/event-stream`). */
+    token: string;
+    /** Milliseconds since epoch; the stream closes at this instant. */
+    expiresAt: number;
+    /** The clamped lifetime actually applied. */
+    ttlSeconds: number;
+}
+interface Events {
+    /**
+     * Publish a payload to one or many channels — one call, up to 500 channels,
+     * so fanning out to every member of a room is a single request.
+     *
+     * Returns how many live subscriber connections were counted across the
+     * published channels (a connection matching several of them counts once per
+     * channel). `delivered: 0` is not an error — it means nobody is listening
+     * right now, which is normal for a nudge.
+     *
+     * Payloads are capped at 32k serialized characters: publish ids and let the
+     * client fetch, not documents.
+     *
+     * @throws MindStudioError on invalid channels, an oversize payload, or a
+     *   platform failure. Unlike `stream()`, publishing is an explicit act and
+     *   failures are not swallowed.
+     */
+    publish(channels: string | string[], data: unknown): Promise<{
+        delivered: number;
+    }>;
+    /**
+     * Mint a subscribe token for an explicit list of channels (up to 100, exact
+     * names — letters, digits, `: _ - .`, no wildcards). Do your authorization
+     * first; whoever holds the returned token WILL receive those channels'
+     * events for its lifetime.
+     *
+     * Return the result from your method (`return await events.grant(...)`);
+     * the client passes `result.token` to the events stream (the frontend SDK's
+     * `getToken`, or `Authorization: Bearer` on `GET /_/events` for an external
+     * client).
+     */
+    grant(channels: string | string[], options?: EventGrantOptions): Promise<EventGrantResult>;
+}
+
 /**
  * JSON Schema support for task-agent structured output.
  *
@@ -3591,6 +3643,7 @@ declare class MindStudioAgent$1 {
     private _voice;
     private _analytics;
     private _email;
+    private _events;
     /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
     private _authType;
     /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -3941,6 +3994,23 @@ declare class MindStudioAgent$1 {
      * ```
      */
     get analytics(): Analytics;
+    /**
+     * The `events` namespace — server→client realtime. `publish()` pushes to
+     * named channels; `grant()` mints the subscribe token a client presents to
+     * the platform-held events stream. See {@link Events} for the channel-shape
+     * and at-most-once semantics.
+     *
+     * @example
+     * ```ts
+     * import { auth, events } from '@mindstudio-ai/agent';
+     *
+     * export async function watchJobs() {
+     *   auth.requireRole('operator');
+     *   return await events.grant(`jobs:${auth.userId}`); // { token, expiresAt, ttlSeconds }
+     * }
+     * ```
+     */
+    get events(): Events;
     /**
      * Outbound email: sending, the per-recipient delivery log, blast stats, and
      * this app's unsubscribe list.
@@ -4031,6 +4101,16 @@ declare class MindStudioAgent$1 {
      * retry a read itself.
      */
     private _emailRequest;
+    /**
+     * @internal Transport for the `events` namespace —
+     * POST /_internal/v2/app-events/<op> with the raw hook token.
+     *
+     * No 429 retry: a retried publish is a duplicate nudge, and grants are
+     * cheap for the caller to re-request. Errors throw (unlike `stream()`) —
+     * publishing is an explicit act, and "nobody was listening" is expressed as
+     * `delivered: 0`, never as an HTTP failure.
+     */
+    private _eventsRequest;
     private _analyticsRequest;
     /**
      * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data
@@ -4157,6 +4237,11 @@ declare class MindStudioAgent$1 {
      * page changes (e.g. a short URL's target). Omit `paths` (or pass an empty
      * array) to purge every snapshot for the app.
      *
+     * `paths` are this app's OWN route paths (`/u/abc`), whatever host the page is
+     * served on. If another app mounts this one under a path prefix, the copies
+     * cached at that prefix are purged too — no need to know or pass the mount
+     * path.
+     *
      * Raw hook-token call (mirrors `reportIssue`) — the appId comes from the
      * token. Backend / managed-context only.
      *
@@ -11452,6 +11537,27 @@ declare const analytics: Analytics;
  * ```
  */
 declare const email: Email;
+/**
+ * Server→client realtime — publish to named channels and mint subscribe
+ * grants. A channel is an audience, and a method decides who is in it; events
+ * are at-most-once nudges (subscribe for speed, reconcile for truth). See
+ * {@link Events}.
+ *
+ * @example
+ * ```ts
+ * import { auth, events } from '@mindstudio-ai/agent';
+ *
+ * // The subscribe door is one of your own methods:
+ * export async function watchJobs() {
+ *   auth.requireRole('operator');
+ *   return await events.grant(`jobs:${auth.userId}`); // { token, expiresAt, ttlSeconds }
+ * }
+ *
+ * // Anything can publish — a method, a cron, a webhook handler:
+ * await events.publish(`jobs:${job.operator}`, { type: 'job', id: job.id });
+ * ```
+ */
+declare const events: Events;
 /**
  * Originating-session identity for this invocation — set when the method was
  * triggered by a conversational surface (a voice call's tool use, an
@@ -11544,6 +11650,9 @@ declare const reportIssue: (input: ReportIssueInput) => Promise<ReportedIssue>;
  * on their next visit. Bound to the default singleton. Backend / managed-context
  * only. Omit `paths` (or pass an empty array) to purge every snapshot.
  *
+ * Pass this app's own route paths; snapshots of those routes cached under
+ * another app's mount prefix are purged along with them.
+ *
  * @example
  * ```ts
  * import { prerender } from '@mindstudio-ai/agent';
@@ -11559,4 +11668,4 @@ declare const prerender: {
     }>;
 };
 
-export { type Accessor, type ActiveCampaignAddNoteStepInput, type ActiveCampaignAddNoteStepOutput, type ActiveCampaignCreateContactStepInput, type ActiveCampaignCreateContactStepOutput, type AddSubtitlesToVideoStepInput, type AddSubtitlesToVideoStepOutput, type AgentInfo, type AgentOptions, type AggregateRow, type AggregateSelect, type AggregateTerm, type AiSourceVendor, type AirtableCreateUpdateRecordStepInput, type AirtableCreateUpdateRecordStepOutput, type AirtableDeleteRecordStepInput, type AirtableDeleteRecordStepOutput, type AirtableGetRecordStepInput, type AirtableGetRecordStepOutput, type AirtableGetTableRecordsStepInput, type AirtableGetTableRecordsStepOutput, type Analytics, type AnalyticsDateRange, type AnalyticsDimension, type AnalyticsFilter, type AnalyticsFilterOp, type AnalyticsGranularity, type AnalyticsMetric, type AnalyticsQueryResponse, type AnalyticsQueryResultRow, type AnalyticsQuerySpec, type AnalyticsReadOptions, type AnalyzeImageStepInput, type AnalyzeImageStepOutput, type AnalyzeVideoStepInput, type AnalyzeVideoStepOutput, type AppAuthContext, type AppContextResult, type AppDatabase, type AppDatabaseColumnSchema, type AppDatabaseTable, type AppRoleAssignment, AuthContext, type AuthTableConfig, type BatchStepInput, type BatchStepResult, type Batchable, type CaptureThumbnailStepInput, type CaptureThumbnailStepOutput, type CheckAppRoleStepInput, type CheckAppRoleStepOutput, type CodaCreateUpdatePageStepInput, type CodaCreateUpdatePageStepOutput, type CodaCreateUpdateRowStepInput, type CodaCreateUpdateRowStepOutput, type CodaFindRowStepInput, type CodaFindRowStepOutput, type CodaGetPageStepInput, type CodaGetPageStepOutput, type CodaGetTableRowsStepInput, type CodaGetTableRowsStepOutput, type Connection, type ConnectorActionDetail, type ConnectorService, type ConvertPdfToImagesStepInput, type ConvertPdfToImagesStepOutput, type CrawlerBucket, type CrawlerHit, type CrawlerOverview, type CreateDataSourceStepInput, type CreateDataSourceStepOutput, type CreateGmailDraftStepInput, type CreateGmailDraftStepOutput, type CreateGoogleCalendarEventStepInput, type CreateGoogleCalendarEventStepOutput, type CreateGoogleDocStepInput, type CreateGoogleDocStepOutput, type CreateGoogleSheetStepInput, type CreateGoogleSheetStepOutput, type Db, type DefineStoreOptions, type DefineTableOptions, type DeleteDataSourceDocumentStepInput, type DeleteDataSourceDocumentStepOutput, type DeleteDataSourceStepInput, type DeleteDataSourceStepOutput, type DeleteGmailEmailStepInput, type DeleteGmailEmailStepOutput, type DeleteGoogleCalendarEventStepInput, type DeleteGoogleCalendarEventStepOutput, type DeleteGoogleSheetRowsStepInput, type DeleteGoogleSheetRowsStepOutput, type DetectChangesStepInput, type DetectChangesStepOutput, type DetectPIIStepInput, type DetectPIIStepOutput, type DiscordEditMessageStepInput, type DiscordEditMessageStepOutput, type DiscordSendFollowUpStepInput, type DiscordSendFollowUpStepOutput, type DiscordSendMessageStepInput, type DiscordSendMessageStepOutput, type DownloadVideoStepInput, type DownloadVideoStepOutput, type EnhanceImageGenerationPromptStepInput, type EnhanceImageGenerationPromptStepOutput, type EnhanceVideoGenerationPromptStepInput, type EnhanceVideoGenerationPromptStepOutput, type EnrichPersonStepInput, type EnrichPersonStepOutput, type ExecuteStepBatchOptions, type ExecuteStepBatchResult, type ExtractAudioFromVideoStepInput, type ExtractAudioFromVideoStepOutput, type ExtractTextStepInput, type ExtractTextStepOutput, type FetchDataSourceDocumentStepInput, type FetchDataSourceDocumentStepOutput, type FetchGoogleDocStepInput, type FetchGoogleDocStepOutput, type FetchGoogleSheetStepInput, type FetchGoogleSheetStepOutput, type FetchSlackChannelHistoryStepInput, type FetchSlackChannelHistoryStepOutput, type FetchYoutubeCaptionsStepInput, type FetchYoutubeCaptionsStepOutput, type FetchYoutubeChannelStepInput, type FetchYoutubeChannelStepOutput, type FetchYoutubeCommentsStepInput, type FetchYoutubeCommentsStepOutput, type FetchYoutubeVideoStepInput, type FetchYoutubeVideoStepOutput, type FileAccess, type Files, type FromSchema, type Generate3dModelStepInput, type Generate3dModelStepOutput, type GenerateAssetStepInput, type GenerateAssetStepOutput, type GenerateChartStepInput, type GenerateChartStepOutput, type GenerateImageStepInput, type GenerateImageStepOutput, type GenerateLipsyncStepInput, type GenerateLipsyncStepOutput, type GenerateMusicStepInput, type GenerateMusicStepOutput, type GeneratePdfStepInput, type GeneratePdfStepOutput, type GenerateStaticVideoFromImageStepInput, type GenerateStaticVideoFromImageStepOutput, type GenerateTextStepInput, type GenerateTextStepOutput, type GenerateVideoStepInput, type GenerateVideoStepOutput, type GetGmailAttachmentsStepInput, type GetGmailAttachmentsStepOutput, type GetGmailDraftStepInput, type GetGmailDraftStepOutput, type GetGmailEmailStepInput, type GetGmailEmailStepOutput, type GetGmailUnreadCountStepInput, type GetGmailUnreadCountStepOutput, type GetGoogleCalendarEventStepInput, type GetGoogleCalendarEventStepOutput, type GetGoogleDriveFileStepInput, type GetGoogleDriveFileStepOutput, type GetGoogleSheetInfoStepInput, type GetGoogleSheetInfoStepOutput, type GetMediaMetadataStepInput, type GetMediaMetadataStepOutput, type HubspotCreateCompanyStepInput, type HubspotCreateCompanyStepOutput, type HubspotCreateContactStepInput, type HubspotCreateContactStepOutput, type HubspotGetCompanyStepInput, type HubspotGetCompanyStepOutput, type HubspotGetContactStepInput, type HubspotGetContactStepOutput, type HunterApiCompanyEnrichmentStepInput, type HunterApiCompanyEnrichmentStepOutput, type HunterApiDomainSearchStepInput, type HunterApiDomainSearchStepOutput, type HunterApiEmailFinderStepInput, type HunterApiEmailFinderStepOutput, type HunterApiEmailVerificationStepInput, type HunterApiEmailVerificationStepOutput, type HunterApiPersonEnrichmentStepInput, type HunterApiPersonEnrichmentStepOutput, type ImageFaceSwapStepInput, type ImageFaceSwapStepOutput, type ImageRemoveWatermarkStepInput, type ImageRemoveWatermarkStepOutput, type InsertVideoClipsStepInput, type InsertVideoClipsStepOutput, type Jewel, type JewelConfig, type JewelGradeContext, type JewelMethod, type JewelMethodInput, type JewelPairRecord, type JewelProposal, type JewelProposeOutcome, type JewelProposeResult, type JewelQueueItem, type JewelQueueResolution, type JewelQueueResolveResult, type JewelRunParams, type JewelVerdict, type JewelsApi, type JsonObjectSchema, type JsonSchema, type JsonSchemaTypeName, type ListAgentsResult, type ListDataSourcesStepInput, type ListDataSourcesStepOutput, type ListGmailDraftsStepInput, type ListGmailDraftsStepOutput, type ListGmailLabelsStepInput, type ListGmailLabelsStepOutput, type ListGoogleCalendarEventsStepInput, type ListGoogleCalendarEventsStepOutput, type ListGoogleDriveFilesStepInput, type ListGoogleDriveFilesStepOutput, type ListOptions, type ListRecentGmailEmailsStepInput, type ListRecentGmailEmailsStepOutput, type LiveNow, type LogicStepInput, type LogicStepOutput, type MakeDotComRunScenarioStepInput, type MakeDotComRunScenarioStepOutput, type MapPoint, type MergeAudioStepInput, type MergeAudioStepOutput, type MergeVideosStepInput, type MergeVideosStepOutput, type MeshyAnimateStepInput, type MeshyAnimateStepOutput, type MeshyImageTo3dStepInput, type MeshyImageTo3dStepOutput, type MeshyRemeshStepInput, type MeshyRemeshStepOutput, type MeshyRigStepInput, type MeshyRigStepOutput, type MeshyTextTo3dStepInput, type MeshyTextTo3dStepOutput, type MeshyTextureStepInput, type MeshyTextureStepOutput, MindStudioAgent, MindStudioError, type MindStudioModel, type MindStudioModelSummary, type MixAudioIntoVideoStepInput, type MixAudioIntoVideoStepOutput, type ModelType, type MonacoSnippet, type MonacoSnippetField, type MonacoSnippetFieldType, type MuteVideoStepInput, type MuteVideoStepOutput, type N8nRunNodeStepInput, type N8nRunNodeStepOutput, type NotionCreatePageStepInput, type NotionCreatePageStepOutput, type NotionUpdatePageStepInput, type NotionUpdatePageStepOutput, type PackagedWorkflow, type PackagedWorkflowInput, type PackagedWorkflowSignature, type ParticlePodcastsFindMentionsStepInput, type ParticlePodcastsFindMentionsStepOutput, type ParticlePodcastsGetEpisodeStepInput, type ParticlePodcastsGetEpisodeStepOutput, type ParticlePodcastsGetEpisodeTranscriptStepInput, type ParticlePodcastsGetEpisodeTranscriptStepOutput, type ParticlePodcastsSearchCompaniesStepInput, type ParticlePodcastsSearchCompaniesStepOutput, type ParticlePodcastsSearchDialogueStepInput, type ParticlePodcastsSearchDialogueStepOutput, type ParticlePodcastsSearchPodcastsStepInput, type ParticlePodcastsSearchPodcastsStepOutput, type PeopleSearchStepInput, type PeopleSearchStepOutput, type PostToLinkedInStepInput, type PostToLinkedInStepOutput, type PostToSlackChannelStepInput, type PostToSlackChannelStepOutput, type PostToXStepInput, type PostToXStepOutput, type PostToZapierStepInput, type PostToZapierStepOutput, type Predicate, type PushInput, type PutOptions, Query, type QueryDataSourceStepInput, type QueryDataSourceStepOutput, type QueryExternalDatabaseStepInput, type QueryExternalDatabaseStepOutput, RawQuery, type RedactPIIStepInput, type RedactPIIStepOutput, type RemoveBackgroundFromImageStepInput, type RemoveBackgroundFromImageStepOutput, type ReplyToGmailEmailStepInput, type ReplyToGmailEmailStepOutput, type ReportIssueInput, type ReportedIssue, type RequestContext, type ResizeVideoStepInput, type ResizeVideoStepOutput, type ResolvedUser, Roles, type RunAgentOptions, type RunAgentResult, type RunFromConnectorRegistryStepInput, type RunFromConnectorRegistryStepOutput, type RunPackagedWorkflowStepInput, type RunPackagedWorkflowStepOutput, type RunTaskOptions, type RunTaskOptionsWithExample, type RunTaskOptionsWithSchema, type RunTaskResult, type SchemaValidationError, type ScrapeLinkedInCompanyStepInput, type ScrapeLinkedInCompanyStepOutput, type ScrapeLinkedInProfileStepInput, type ScrapeLinkedInProfileStepOutput, type ScrapeUrlStepInput, type ScrapeUrlStepOutput, type ScrapeXPostStepInput, type ScrapeXPostStepOutput, type ScrapeXProfileStepInput, type ScrapeXProfileStepOutput, type ScreenshotUrlStepInput, type ScreenshotUrlStepOutput, type SearchGmailEmailsStepInput, type SearchGmailEmailsStepOutput, type SearchGoogleCalendarEventsStepInput, type SearchGoogleCalendarEventsStepOutput, type SearchGoogleDriveStepInput, type SearchGoogleDriveStepOutput, type SearchGoogleImagesStepInput, type SearchGoogleImagesStepOutput, type SearchGoogleNewsStepInput, type SearchGoogleNewsStepOutput, type SearchGoogleStepInput, type SearchGoogleStepOutput, type SearchGoogleTrendsStepInput, type SearchGoogleTrendsStepOutput, type SearchPerplexityStepInput, type SearchPerplexityStepOutput, type SearchXPostsStepInput, type SearchXPostsStepOutput, type SearchYoutubeStepInput, type SearchYoutubeStepOutput, type SearchYoutubeTrendsStepInput, type SearchYoutubeTrendsStepOutput, type SendEmailStepInput, type SendEmailStepOutput, type SendGmailDraftStepInput, type SendGmailDraftStepOutput, type SendGmailMessageStepInput, type SendGmailMessageStepOutput, type SendSMSStepInput, type SendSMSStepOutput, type SendSlackDirectMessageStepInput, type SendSlackDirectMessageStepOutput, type SessionContext, type SetGmailReadStatusStepInput, type SetGmailReadStatusStepOutput, type SetRunTitleStepInput, type SetRunTitleStepOutput, type SetVariableStepInput, type SetVariableStepOutput, type StepCostEstimateEntry, type StepExecutionMeta, type StepExecutionOptions, type StepExecutionResult, type StepInputMap, type StepLogEvent, type StepMetadata, type StepMethods, type StepName, type StepOutputMap, Store, type StoredFile, type SystemFields, Table, type TaskEvent, type TaskToolCall, type TaskToolConfig, type TaskUsage, type TelegramEditMessageStepInput, type TelegramEditMessageStepOutput, type TelegramReplyToMessageStepInput, type TelegramReplyToMessageStepOutput, type TelegramSendAudioStepInput, type TelegramSendAudioStepOutput, type TelegramSendFileStepInput, type TelegramSendFileStepOutput, type TelegramSendImageStepInput, type TelegramSendImageStepOutput, type TelegramSendMessageStepInput, type TelegramSendMessageStepOutput, type TelegramSendVideoStepInput, type TelegramSendVideoStepOutput, type TelegramSetTypingStepInput, type TelegramSetTypingStepOutput, type TextToSpeechStepInput, type TextToSpeechStepOutput, type TopSource, type TranscribeAudioStepInput, type TranscribeAudioStepOutput, type TrimMediaStepInput, type TrimMediaStepOutput, type UpdateGmailLabelsStepInput, type UpdateGmailLabelsStepOutput, type UpdateGoogleCalendarEventStepInput, type UpdateGoogleCalendarEventStepOutput, type UpdateGoogleDocStepInput, type UpdateGoogleDocStepOutput, type UpdateGoogleSheetStepInput, type UpdateGoogleSheetStepOutput, type UpdateInput, type UploadDataSourceDocumentStepInput, type UploadDataSourceDocumentStepOutput, type UploadFileResult, type UploadToken, type UpscaleImageStepInput, type UpscaleImageStepOutput, type UpscaleVideoStepInput, type UpscaleVideoStepOutput, type User, type UserInfoResult, type UserMessageStepInput, type UserMessageStepOutput, type VideoFaceSwapStepInput, type VideoFaceSwapStepOutput, type VideoRemoveBackgroundStepInput, type VideoRemoveBackgroundStepOutput, type VideoRemoveWatermarkStepInput, type VideoRemoveWatermarkStepOutput, type Voice, type VoiceCallResult, type WatermarkImageStepInput, type WatermarkImageStepOutput, type WatermarkVideoStepInput, type WatermarkVideoStepOutput, type YouDotComFinanceResearchStepInput, type YouDotComFinanceResearchStepOutput, type YouDotComGetPageContentStepInput, type YouDotComGetPageContentStepOutput, type YouDotComLiveNewsStepInput, type YouDotComLiveNewsStepOutput, type YouDotComWebResearchStepInput, type YouDotComWebResearchStepOutput, type YouDotComWebSearchStepInput, type YouDotComWebSearchStepOutput, analytics, auth, blockTypeAliases, dataSources, db, mindstudio as default, defineJewel, email, files, getRequestContext, mindstudio, monacoSnippets, prerender, reportIssue, resolveUser, runWithContext, session, stepMetadata, stream, voice, waitUntil };
+export { type Accessor, type ActiveCampaignAddNoteStepInput, type ActiveCampaignAddNoteStepOutput, type ActiveCampaignCreateContactStepInput, type ActiveCampaignCreateContactStepOutput, type AddSubtitlesToVideoStepInput, type AddSubtitlesToVideoStepOutput, type AgentInfo, type AgentOptions, type AggregateRow, type AggregateSelect, type AggregateTerm, type AiSourceVendor, type AirtableCreateUpdateRecordStepInput, type AirtableCreateUpdateRecordStepOutput, type AirtableDeleteRecordStepInput, type AirtableDeleteRecordStepOutput, type AirtableGetRecordStepInput, type AirtableGetRecordStepOutput, type AirtableGetTableRecordsStepInput, type AirtableGetTableRecordsStepOutput, type Analytics, type AnalyticsDateRange, type AnalyticsDimension, type AnalyticsFilter, type AnalyticsFilterOp, type AnalyticsGranularity, type AnalyticsMetric, type AnalyticsQueryResponse, type AnalyticsQueryResultRow, type AnalyticsQuerySpec, type AnalyticsReadOptions, type AnalyzeImageStepInput, type AnalyzeImageStepOutput, type AnalyzeVideoStepInput, type AnalyzeVideoStepOutput, type AppAuthContext, type AppContextResult, type AppDatabase, type AppDatabaseColumnSchema, type AppDatabaseTable, type AppRoleAssignment, AuthContext, type AuthTableConfig, type BatchStepInput, type BatchStepResult, type Batchable, type CaptureThumbnailStepInput, type CaptureThumbnailStepOutput, type CheckAppRoleStepInput, type CheckAppRoleStepOutput, type CodaCreateUpdatePageStepInput, type CodaCreateUpdatePageStepOutput, type CodaCreateUpdateRowStepInput, type CodaCreateUpdateRowStepOutput, type CodaFindRowStepInput, type CodaFindRowStepOutput, type CodaGetPageStepInput, type CodaGetPageStepOutput, type CodaGetTableRowsStepInput, type CodaGetTableRowsStepOutput, type Connection, type ConnectorActionDetail, type ConnectorService, type ConvertPdfToImagesStepInput, type ConvertPdfToImagesStepOutput, type CrawlerBucket, type CrawlerHit, type CrawlerOverview, type CreateDataSourceStepInput, type CreateDataSourceStepOutput, type CreateGmailDraftStepInput, type CreateGmailDraftStepOutput, type CreateGoogleCalendarEventStepInput, type CreateGoogleCalendarEventStepOutput, type CreateGoogleDocStepInput, type CreateGoogleDocStepOutput, type CreateGoogleSheetStepInput, type CreateGoogleSheetStepOutput, type Db, type DefineStoreOptions, type DefineTableOptions, type DeleteDataSourceDocumentStepInput, type DeleteDataSourceDocumentStepOutput, type DeleteDataSourceStepInput, type DeleteDataSourceStepOutput, type DeleteGmailEmailStepInput, type DeleteGmailEmailStepOutput, type DeleteGoogleCalendarEventStepInput, type DeleteGoogleCalendarEventStepOutput, type DeleteGoogleSheetRowsStepInput, type DeleteGoogleSheetRowsStepOutput, type DetectChangesStepInput, type DetectChangesStepOutput, type DetectPIIStepInput, type DetectPIIStepOutput, type DiscordEditMessageStepInput, type DiscordEditMessageStepOutput, type DiscordSendFollowUpStepInput, type DiscordSendFollowUpStepOutput, type DiscordSendMessageStepInput, type DiscordSendMessageStepOutput, type DownloadVideoStepInput, type DownloadVideoStepOutput, type EnhanceImageGenerationPromptStepInput, type EnhanceImageGenerationPromptStepOutput, type EnhanceVideoGenerationPromptStepInput, type EnhanceVideoGenerationPromptStepOutput, type EnrichPersonStepInput, type EnrichPersonStepOutput, type EventGrantOptions, type EventGrantResult, type Events, type ExecuteStepBatchOptions, type ExecuteStepBatchResult, type ExtractAudioFromVideoStepInput, type ExtractAudioFromVideoStepOutput, type ExtractTextStepInput, type ExtractTextStepOutput, type FetchDataSourceDocumentStepInput, type FetchDataSourceDocumentStepOutput, type FetchGoogleDocStepInput, type FetchGoogleDocStepOutput, type FetchGoogleSheetStepInput, type FetchGoogleSheetStepOutput, type FetchSlackChannelHistoryStepInput, type FetchSlackChannelHistoryStepOutput, type FetchYoutubeCaptionsStepInput, type FetchYoutubeCaptionsStepOutput, type FetchYoutubeChannelStepInput, type FetchYoutubeChannelStepOutput, type FetchYoutubeCommentsStepInput, type FetchYoutubeCommentsStepOutput, type FetchYoutubeVideoStepInput, type FetchYoutubeVideoStepOutput, type FileAccess, type Files, type FromSchema, type Generate3dModelStepInput, type Generate3dModelStepOutput, type GenerateAssetStepInput, type GenerateAssetStepOutput, type GenerateChartStepInput, type GenerateChartStepOutput, type GenerateImageStepInput, type GenerateImageStepOutput, type GenerateLipsyncStepInput, type GenerateLipsyncStepOutput, type GenerateMusicStepInput, type GenerateMusicStepOutput, type GeneratePdfStepInput, type GeneratePdfStepOutput, type GenerateStaticVideoFromImageStepInput, type GenerateStaticVideoFromImageStepOutput, type GenerateTextStepInput, type GenerateTextStepOutput, type GenerateVideoStepInput, type GenerateVideoStepOutput, type GetGmailAttachmentsStepInput, type GetGmailAttachmentsStepOutput, type GetGmailDraftStepInput, type GetGmailDraftStepOutput, type GetGmailEmailStepInput, type GetGmailEmailStepOutput, type GetGmailUnreadCountStepInput, type GetGmailUnreadCountStepOutput, type GetGoogleCalendarEventStepInput, type GetGoogleCalendarEventStepOutput, type GetGoogleDriveFileStepInput, type GetGoogleDriveFileStepOutput, type GetGoogleSheetInfoStepInput, type GetGoogleSheetInfoStepOutput, type GetMediaMetadataStepInput, type GetMediaMetadataStepOutput, type HubspotCreateCompanyStepInput, type HubspotCreateCompanyStepOutput, type HubspotCreateContactStepInput, type HubspotCreateContactStepOutput, type HubspotGetCompanyStepInput, type HubspotGetCompanyStepOutput, type HubspotGetContactStepInput, type HubspotGetContactStepOutput, type HunterApiCompanyEnrichmentStepInput, type HunterApiCompanyEnrichmentStepOutput, type HunterApiDomainSearchStepInput, type HunterApiDomainSearchStepOutput, type HunterApiEmailFinderStepInput, type HunterApiEmailFinderStepOutput, type HunterApiEmailVerificationStepInput, type HunterApiEmailVerificationStepOutput, type HunterApiPersonEnrichmentStepInput, type HunterApiPersonEnrichmentStepOutput, type ImageFaceSwapStepInput, type ImageFaceSwapStepOutput, type ImageRemoveWatermarkStepInput, type ImageRemoveWatermarkStepOutput, type InsertVideoClipsStepInput, type InsertVideoClipsStepOutput, type Jewel, type JewelConfig, type JewelGradeContext, type JewelMethod, type JewelMethodInput, type JewelPairRecord, type JewelProposal, type JewelProposeOutcome, type JewelProposeResult, type JewelQueueItem, type JewelQueueResolution, type JewelQueueResolveResult, type JewelRunParams, type JewelVerdict, type JewelsApi, type JsonObjectSchema, type JsonSchema, type JsonSchemaTypeName, type ListAgentsResult, type ListDataSourcesStepInput, type ListDataSourcesStepOutput, type ListGmailDraftsStepInput, type ListGmailDraftsStepOutput, type ListGmailLabelsStepInput, type ListGmailLabelsStepOutput, type ListGoogleCalendarEventsStepInput, type ListGoogleCalendarEventsStepOutput, type ListGoogleDriveFilesStepInput, type ListGoogleDriveFilesStepOutput, type ListOptions, type ListRecentGmailEmailsStepInput, type ListRecentGmailEmailsStepOutput, type LiveNow, type LogicStepInput, type LogicStepOutput, type MakeDotComRunScenarioStepInput, type MakeDotComRunScenarioStepOutput, type MapPoint, type MergeAudioStepInput, type MergeAudioStepOutput, type MergeVideosStepInput, type MergeVideosStepOutput, type MeshyAnimateStepInput, type MeshyAnimateStepOutput, type MeshyImageTo3dStepInput, type MeshyImageTo3dStepOutput, type MeshyRemeshStepInput, type MeshyRemeshStepOutput, type MeshyRigStepInput, type MeshyRigStepOutput, type MeshyTextTo3dStepInput, type MeshyTextTo3dStepOutput, type MeshyTextureStepInput, type MeshyTextureStepOutput, MindStudioAgent, MindStudioError, type MindStudioModel, type MindStudioModelSummary, type MixAudioIntoVideoStepInput, type MixAudioIntoVideoStepOutput, type ModelType, type MonacoSnippet, type MonacoSnippetField, type MonacoSnippetFieldType, type MuteVideoStepInput, type MuteVideoStepOutput, type N8nRunNodeStepInput, type N8nRunNodeStepOutput, type NotionCreatePageStepInput, type NotionCreatePageStepOutput, type NotionUpdatePageStepInput, type NotionUpdatePageStepOutput, type PackagedWorkflow, type PackagedWorkflowInput, type PackagedWorkflowSignature, type ParticlePodcastsFindMentionsStepInput, type ParticlePodcastsFindMentionsStepOutput, type ParticlePodcastsGetEpisodeStepInput, type ParticlePodcastsGetEpisodeStepOutput, type ParticlePodcastsGetEpisodeTranscriptStepInput, type ParticlePodcastsGetEpisodeTranscriptStepOutput, type ParticlePodcastsSearchCompaniesStepInput, type ParticlePodcastsSearchCompaniesStepOutput, type ParticlePodcastsSearchDialogueStepInput, type ParticlePodcastsSearchDialogueStepOutput, type ParticlePodcastsSearchPodcastsStepInput, type ParticlePodcastsSearchPodcastsStepOutput, type PeopleSearchStepInput, type PeopleSearchStepOutput, type PostToLinkedInStepInput, type PostToLinkedInStepOutput, type PostToSlackChannelStepInput, type PostToSlackChannelStepOutput, type PostToXStepInput, type PostToXStepOutput, type PostToZapierStepInput, type PostToZapierStepOutput, type Predicate, type PushInput, type PutOptions, Query, type QueryDataSourceStepInput, type QueryDataSourceStepOutput, type QueryExternalDatabaseStepInput, type QueryExternalDatabaseStepOutput, RawQuery, type RedactPIIStepInput, type RedactPIIStepOutput, type RemoveBackgroundFromImageStepInput, type RemoveBackgroundFromImageStepOutput, type ReplyToGmailEmailStepInput, type ReplyToGmailEmailStepOutput, type ReportIssueInput, type ReportedIssue, type RequestContext, type ResizeVideoStepInput, type ResizeVideoStepOutput, type ResolvedUser, Roles, type RunAgentOptions, type RunAgentResult, type RunFromConnectorRegistryStepInput, type RunFromConnectorRegistryStepOutput, type RunPackagedWorkflowStepInput, type RunPackagedWorkflowStepOutput, type RunTaskOptions, type RunTaskOptionsWithExample, type RunTaskOptionsWithSchema, type RunTaskResult, type SchemaValidationError, type ScrapeLinkedInCompanyStepInput, type ScrapeLinkedInCompanyStepOutput, type ScrapeLinkedInProfileStepInput, type ScrapeLinkedInProfileStepOutput, type ScrapeUrlStepInput, type ScrapeUrlStepOutput, type ScrapeXPostStepInput, type ScrapeXPostStepOutput, type ScrapeXProfileStepInput, type ScrapeXProfileStepOutput, type ScreenshotUrlStepInput, type ScreenshotUrlStepOutput, type SearchGmailEmailsStepInput, type SearchGmailEmailsStepOutput, type SearchGoogleCalendarEventsStepInput, type SearchGoogleCalendarEventsStepOutput, type SearchGoogleDriveStepInput, type SearchGoogleDriveStepOutput, type SearchGoogleImagesStepInput, type SearchGoogleImagesStepOutput, type SearchGoogleNewsStepInput, type SearchGoogleNewsStepOutput, type SearchGoogleStepInput, type SearchGoogleStepOutput, type SearchGoogleTrendsStepInput, type SearchGoogleTrendsStepOutput, type SearchPerplexityStepInput, type SearchPerplexityStepOutput, type SearchXPostsStepInput, type SearchXPostsStepOutput, type SearchYoutubeStepInput, type SearchYoutubeStepOutput, type SearchYoutubeTrendsStepInput, type SearchYoutubeTrendsStepOutput, type SendEmailStepInput, type SendEmailStepOutput, type SendGmailDraftStepInput, type SendGmailDraftStepOutput, type SendGmailMessageStepInput, type SendGmailMessageStepOutput, type SendSMSStepInput, type SendSMSStepOutput, type SendSlackDirectMessageStepInput, type SendSlackDirectMessageStepOutput, type SessionContext, type SetGmailReadStatusStepInput, type SetGmailReadStatusStepOutput, type SetRunTitleStepInput, type SetRunTitleStepOutput, type SetVariableStepInput, type SetVariableStepOutput, type StepCostEstimateEntry, type StepExecutionMeta, type StepExecutionOptions, type StepExecutionResult, type StepInputMap, type StepLogEvent, type StepMetadata, type StepMethods, type StepName, type StepOutputMap, Store, type StoredFile, type SystemFields, Table, type TaskEvent, type TaskToolCall, type TaskToolConfig, type TaskUsage, type TelegramEditMessageStepInput, type TelegramEditMessageStepOutput, type TelegramReplyToMessageStepInput, type TelegramReplyToMessageStepOutput, type TelegramSendAudioStepInput, type TelegramSendAudioStepOutput, type TelegramSendFileStepInput, type TelegramSendFileStepOutput, type TelegramSendImageStepInput, type TelegramSendImageStepOutput, type TelegramSendMessageStepInput, type TelegramSendMessageStepOutput, type TelegramSendVideoStepInput, type TelegramSendVideoStepOutput, type TelegramSetTypingStepInput, type TelegramSetTypingStepOutput, type TextToSpeechStepInput, type TextToSpeechStepOutput, type TopSource, type TranscribeAudioStepInput, type TranscribeAudioStepOutput, type TrimMediaStepInput, type TrimMediaStepOutput, type UpdateGmailLabelsStepInput, type UpdateGmailLabelsStepOutput, type UpdateGoogleCalendarEventStepInput, type UpdateGoogleCalendarEventStepOutput, type UpdateGoogleDocStepInput, type UpdateGoogleDocStepOutput, type UpdateGoogleSheetStepInput, type UpdateGoogleSheetStepOutput, type UpdateInput, type UploadDataSourceDocumentStepInput, type UploadDataSourceDocumentStepOutput, type UploadFileResult, type UploadToken, type UpscaleImageStepInput, type UpscaleImageStepOutput, type UpscaleVideoStepInput, type UpscaleVideoStepOutput, type User, type UserInfoResult, type UserMessageStepInput, type UserMessageStepOutput, type VideoFaceSwapStepInput, type VideoFaceSwapStepOutput, type VideoRemoveBackgroundStepInput, type VideoRemoveBackgroundStepOutput, type VideoRemoveWatermarkStepInput, type VideoRemoveWatermarkStepOutput, type Voice, type VoiceCallResult, type WatermarkImageStepInput, type WatermarkImageStepOutput, type WatermarkVideoStepInput, type WatermarkVideoStepOutput, type YouDotComFinanceResearchStepInput, type YouDotComFinanceResearchStepOutput, type YouDotComGetPageContentStepInput, type YouDotComGetPageContentStepOutput, type YouDotComLiveNewsStepInput, type YouDotComLiveNewsStepOutput, type YouDotComWebResearchStepInput, type YouDotComWebResearchStepOutput, type YouDotComWebSearchStepInput, type YouDotComWebSearchStepOutput, analytics, auth, blockTypeAliases, dataSources, db, mindstudio as default, defineJewel, email, events, files, getRequestContext, mindstudio, monacoSnippets, prerender, reportIssue, resolveUser, runWithContext, session, stepMetadata, stream, voice, waitUntil };

package/dist/index.js

@@ -478,7 +478,7 @@ var AuthContext = class {
   constructor(ctx) {
     this.userId = ctx.userId;
     this._roleAssignments = ctx.roleAssignments;
-    this.roles = ctx.roleAssignments.filter((a) => a.userId === ctx.userId).map((a) => a.roleName);
+    this.roles = ctx.userId == null ? [] : ctx.roleAssignments.filter((a) => a.userId === ctx.userId).map((a) => a.roleName);
   }
   /**
    * Check if the current user has **any** of the given roles.
@@ -3072,6 +3072,18 @@ function createEmail(call) {
   };
 }
 
+// src/events/index.ts
+function createEvents(call) {
+  return {
+    publish(channels, data) {
+      return call("publish", { channels, data });
+    },
+    grant(channels, options) {
+      return call("grant", { channels, ttlSeconds: options?.ttlSeconds });
+    }
+  };
+}
+
 // src/task/index.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
@@ -4819,7 +4831,7 @@ async function attemptTurn(httpConfig, body) {
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
-    const events = [];
+    const events2 = [];
     let text = "";
     const toolCalls = [];
     let turn = null;
@@ -4841,7 +4853,7 @@ async function attemptTurn(httpConfig, body) {
       }
       if (event.type === "turn") {
         turn = {
-          events,
+          events: events2,
           text,
           toolCalls,
           stopReason: typeof event.stopReason === "string" ? event.stopReason : "end_turn",
@@ -4859,7 +4871,7 @@ async function attemptTurn(httpConfig, body) {
           input: event.input ?? {}
         });
       }
-      events.push(event);
+      events2.push(event);
     };
     while (true) {
       let stallTimer;
@@ -5786,6 +5798,7 @@ var MindStudioAgent = class {
   _voice;
   _analytics;
   _email;
+  _events;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -6830,6 +6843,25 @@ var MindStudioAgent = class {
       this._analyticsRequest.bind(this)
     );
   }
+  /**
+   * The `events` namespace — server→client realtime. `publish()` pushes to
+   * named channels; `grant()` mints the subscribe token a client presents to
+   * the platform-held events stream. See {@link Events} for the channel-shape
+   * and at-most-once semantics.
+   *
+   * @example
+   * ```ts
+   * import { auth, events } from '@mindstudio-ai/agent';
+   *
+   * export async function watchJobs() {
+   *   auth.requireRole('operator');
+   *   return await events.grant(`jobs:${auth.userId}`); // { token, expiresAt, ttlSeconds }
+   * }
+   * ```
+   */
+  get events() {
+    return this._events ??= createEvents(this._eventsRequest.bind(this));
+  }
   /**
    * Outbound email: sending, the per-recipient delivery log, blast stats, and
    * this app's unsubscribe list.
@@ -7010,6 +7042,21 @@ var MindStudioAgent = class {
       fallbackCode: "email_error"
     });
   }
+  /**
+   * @internal Transport for the `events` namespace —
+   * POST /_internal/v2/app-events/<op> with the raw hook token.
+   *
+   * No 429 retry: a retried publish is a duplicate nudge, and grants are
+   * cheap for the caller to re-request. Errors throw (unlike `stream()`) —
+   * publishing is an explicit act, and "nobody was listening" is expressed as
+   * `delivered: 0`, never as an HTTP failure.
+   */
+  async _eventsRequest(op, body) {
+    return this._brokeredRequest("app-events", op, body, {
+      fallbackMessage: "Events call failed",
+      fallbackCode: "events_error"
+    });
+  }
   async _analyticsRequest(op, body) {
     const call = () => this._brokeredRequest("analytics", op, body, {
       fallbackMessage: "Analytics read failed",
@@ -7398,6 +7445,11 @@ var MindStudioAgent = class {
    * page changes (e.g. a short URL's target). Omit `paths` (or pass an empty
    * array) to purge every snapshot for the app.
    *
+   * `paths` are this app's OWN route paths (`/u/abc`), whatever host the page is
+   * served on. If another app mounts this one under a path prefix, the copies
+   * cached at that prefix are purged too — no need to know or pass the mount
+   * path.
+   *
    * Raw hook-token call (mirrors `reportIssue`) — the appId comes from the
    * token. Backend / managed-context only.
    *
@@ -7921,6 +7973,13 @@ var email = new Proxy({}, {
     return typeof value === "function" ? value.bind(target) : value;
   }
 });
+var events = new Proxy({}, {
+  get(_, prop) {
+    const target = mindstudio.events;
+    const value = Reflect.get(target, prop, target);
+    return typeof value === "function" ? value.bind(target) : value;
+  }
+});
 var session = new Proxy(
   {},
   {
@@ -7950,6 +8009,7 @@ export {
   index_default as default,
   defineJewel,
   email,
+  events,
   files,
   getRequestContext,
   mindstudio,