@mindstudio-ai/agent 0.1.84 → 0.1.86

package/dist/index.d.ts

@@ -1448,8 +1448,10 @@ declare class Store {
 
 /**
  * The `files` namespace — typed, private-by-default file storage for MindStudio
- * apps. The twin of `db`: define a store at module scope, import the handle into
- * route handlers.
+ * apps. Think of a store as a CDN-backed bucket the app talks to, not app-defined
+ * state like a `db` table: the API is *shaped* like `db` (define a store at module
+ * scope, import the handle into route handlers), but its contents are arbitrary
+ * durable blobs, and one store is shared across dev and prod.
  *
  * ```ts
  * // files/uploads.ts
@@ -1498,6 +1500,192 @@ interface Files {
     defineStore(name: string, options?: DefineStoreOptions): Store;
 }
 
+/** @internal Transport: `POST /_internal/v2/datasources/<op>` with the hook token. */
+type DataSourcesTransport = (op: string, body: unknown) => Promise<any>;
+/** Where a retrieved chunk came from — enough to show the user the source. */
+interface Citation {
+    documentId: string;
+    filename: string | null;
+    /** 1-based. Null for formats with no pagination (plain text, html). */
+    pageNumber: number | null;
+    /** Enclosing headings, outermost first. */
+    headingPath: string[];
+    /**
+     * Region of the page this chunk came from, when the format had a layout to
+     * measure — PDFs do, docx and plain text don't. Precise enough to highlight.
+     */
+    boundingBox?: {
+        topLeftX: number;
+        topLeftY: number;
+        bottomRightX: number;
+        bottomRightY: number;
+    };
+    /**
+     * Stable on-domain URL for the source document. Drop it in an `<a href>` —
+     * a same-origin logged-in request authorizes automatically, so there's
+     * nothing to await.
+     */
+    url: string;
+}
+interface SearchHit {
+    /** Provider relevance score. Comparable within a response, not across them. */
+    score: number;
+    /** The matched chunk, prefixed with its heading path for context. */
+    text: string;
+    citation: Citation;
+}
+/**
+ * Per-query overrides.
+ *
+ * These are the settings that are free to change: none of them touch a stored
+ * vector, so they take effect on the next call and cost nothing. Anything that
+ * would require rebuilding the corpus — chunking, the embedding model, whether
+ * chunks are contextualized — is a property of the data source, configured
+ * with `mindstudio-prod datasources config` rather than passed here.
+ *
+ * The defaults come from the data source's own configuration, so most callers
+ * should pass nothing.
+ */
+interface SearchOptions {
+    /** Results to return. Default 5, capped at 50. */
+    topK?: number;
+    /** Drop hits below this score. Provider-specific scale — measure before using. */
+    scoreThreshold?: number;
+    /**
+     * Rerank results with a cross-encoder before returning them. On by default.
+     *
+     * Turn it off on a latency-sensitive path — it adds a round trip for a
+     * meaningful ranking improvement, which is usually the right trade but not
+     * always.
+     */
+    rerank?: boolean;
+    /**
+     * Combine semantic search with exact keyword matching. On by default.
+     *
+     * Keyword matching is what finds part numbers, error codes and proper nouns
+     * that an embedding model never learned. Rarely worth disabling.
+     */
+    hybrid?: boolean;
+}
+interface AddOptions {
+    /**
+     * Required — the extension selects the extraction route. PDFs and office
+     * formats go to a document model; text and CSV are read directly.
+     */
+    filename: string;
+    contentType?: string;
+}
+interface DataSourceDocument {
+    id: string;
+    filename: string | null;
+    status: 'processing' | 'done' | 'error';
+    errorMessage: string | null;
+    chunkCount: number | null;
+    pageCount: number | null;
+    createdAt: string;
+    ingestedAt: string | null;
+}
+/**
+ * A typed handle to one data source. Lazy — nothing executes until a method is
+ * awaited, so it's safe to `defineDataSource()` at module scope and import the
+ * handle into route handlers (same ergonomics as `db.defineTable` and
+ * `files.defineStore`).
+ */
+declare class DataSource {
+    private readonly _slug;
+    private readonly _call;
+    constructor(_slug: string, _call: DataSourcesTransport);
+    get name(): string;
+    /**
+     * Search the corpus.
+     *
+     * Returns chunks ranked by relevance, each with a citation. Searching a
+     * source that doesn't exist yet returns no results rather than throwing —
+     * code may name a corpus the build hasn't populated.
+     */
+    search(query: string, options?: SearchOptions): Promise<{
+        results: SearchHit[];
+    }>;
+    /**
+     * Add a document to the corpus.
+     *
+     * Returns as soon as the document is queued — extraction and embedding run
+     * in the background and take a while, so poll {@link documents} for status
+     * rather than assuming the content is searchable on return.
+     *
+     * **Adding the same bytes twice is free.** Documents are content-addressed,
+     * so a re-add is a no-op when this source has already processed those exact
+     * bytes under its current configuration. Reconfiguring the source is what
+     * makes a re-add do work again — and that is an explicit, owner-triggered
+     * migration, never something a deploy causes.
+     */
+    add(content: Buffer | Uint8Array | string, options: AddOptions): Promise<{
+        document: DataSourceDocument;
+        queued: boolean;
+    }>;
+    /** Every document in the corpus, with ingest status. */
+    documents(): Promise<DataSourceDocument[]>;
+    /** Remove a document and its vectors. */
+    remove(documentId: string): Promise<void>;
+    /**
+     * Create the data source if it doesn't exist yet.
+     *
+     * Rarely needed — `add` and `search` both handle a missing source. Useful
+     * when you want it to exist (and appear in the dashboard) before any
+     * document has been added.
+     */
+    ensure(name?: string): Promise<void>;
+    /**
+     * @internal Content hash of some bytes, matching what the server computes.
+     * Exposed for callers that want to check whether they already added a file.
+     */
+    static contentHash(content: Buffer | Uint8Array | string): string;
+}
+
+/**
+ * The `dataSources` namespace — searchable document corpora for MindStudio
+ * apps. The retrieval half of the platform's managed data layer, shaped like
+ * `db` and `files`: declare a source at module scope, import the handle into
+ * route handlers.
+ *
+ * ```ts
+ * // datasources/policies.ts
+ * import { dataSources } from '@mindstudio-ai/agent';
+ * export const Policies = dataSources.defineDataSource('policies');
+ *
+ * // routes/ask.ts
+ * import { Policies } from '../datasources/policies';
+ *
+ * const { results } = await Policies.search('what are the payment terms?');
+ * const context = results.map((r) => r.text).join('\n\n');
+ * ```
+ *
+ * The platform owns parsing, chunking, embedding, storage and isolation. You
+ * declare what the corpus is and search it; every hit comes back with a
+ * citation pointing at the source document.
+ *
+ * **Corpora are usually built at development time**, not through your app's
+ * UI — the agent adds documents while building, and the app is a consumer.
+ * `add()` exists for apps where users upload documents themselves.
+ *
+ * **A data source is live and shared.** Unlike database tables there is no dev
+ * copy and no per-release isolation: adding or removing a document affects
+ * what the deployed app retrieves, immediately. Scenarios never reset a data
+ * source, and re-ingesting a large corpus costs real money.
+ */
+
+/** The `dataSources` namespace object. */
+interface DataSources {
+    /**
+     * Define a data source. Lazy — nothing executes until you await a method on
+     * the returned {@link DataSource}, so it's safe to call at module scope.
+     *
+     * The source is created on first use if it doesn't exist, so naming one the
+     * build hasn't populated yet is not an error; it just searches empty.
+     */
+    defineDataSource(name: string): DataSource;
+}
+
 /**
  * Types for the task agent runtime.
  *
@@ -1652,6 +1840,7 @@ declare class MindStudioAgent$1 {
     private _db;
     /** @internal Cached Files namespace instance (lazy; no context hydration needed). */
     private _files;
+    private _dataSources;
     /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
     private _authType;
     /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -1931,11 +2120,32 @@ declare class MindStudioAgent$1 {
      * ```
      */
     get files(): Files;
+    /**
+     * Searchable document corpora.
+     *
+     * @example
+     * ```ts
+     * const Policies = agent.dataSources.defineDataSource('policies');
+     * const { results } = await Policies.search('what are the payment terms?');
+     * ```
+     */
+    get dataSources(): DataSources;
     /**
      * @internal Transport for the `files` namespace — POST /_internal/v2/files/<op>
      * with the raw hook token (mirrors `_executeDbBatch`).
      */
     private _filesRequest;
+    /**
+     * @internal Transport for the `dataSources` namespace —
+     * POST /_internal/v2/datasources/<op> with the raw hook token.
+     */
+    private _dataSourcesRequest;
+    /**
+     * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data
+     * planes. Factored out rather than copied per namespace so error handling
+     * can't drift between them.
+     */
+    private _brokeredRequest;
     /**
      * @internal Execute a batch of SQL queries against a managed database.
      * Used as the `executeBatch` callback for Table/Query instances.
@@ -9209,6 +9419,21 @@ declare const db: Db;
  * ```
  */
 declare const files: Files;
+/**
+ * Top-level `dataSources` namespace bound to the default singleton.
+ *
+ * Searchable document corpora. Declare one at module scope and import the
+ * handle; the platform owns parsing, chunking, embedding and isolation.
+ *
+ * @example
+ * ```ts
+ * import { dataSources } from '@mindstudio-ai/agent';
+ *
+ * const Policies = dataSources.defineDataSource('policies');
+ * const { results } = await Policies.search('what are the payment terms?');
+ * ```
+ */
+declare const dataSources: DataSources;
 /**
  * Top-level `stream` function bound to the default singleton.
  *
@@ -9272,4 +9497,4 @@ declare const prerender: {
     }>;
 };
 
-export { type Accessor, type ActiveCampaignAddNoteStepInput, type ActiveCampaignAddNoteStepOutput, type ActiveCampaignCreateContactStepInput, type ActiveCampaignCreateContactStepOutput, type AddSubtitlesToVideoStepInput, type AddSubtitlesToVideoStepOutput, type AgentInfo, type AgentOptions, type AirtableCreateUpdateRecordStepInput, type AirtableCreateUpdateRecordStepOutput, type AirtableDeleteRecordStepInput, type AirtableDeleteRecordStepOutput, type AirtableGetRecordStepInput, type AirtableGetRecordStepOutput, type AirtableGetTableRecordsStepInput, type AirtableGetTableRecordsStepOutput, 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 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 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 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 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 LogicStepInput, type LogicStepOutput, type MakeDotComRunScenarioStepInput, type MakeDotComRunScenarioStepOutput, 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 QueryAppDatabaseStepInput, type QueryAppDatabaseStepOutput, type QueryDataSourceStepInput, type QueryDataSourceStepOutput, type QueryExternalDatabaseStepInput, type QueryExternalDatabaseStepOutput, 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 RunTaskResult, 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 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 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 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, auth, blockTypeAliases, db, mindstudio as default, files, getRequestContext, mindstudio, monacoSnippets, prerender, reportIssue, resolveUser, runWithContext, stepMetadata, stream };
+export { type Accessor, type ActiveCampaignAddNoteStepInput, type ActiveCampaignAddNoteStepOutput, type ActiveCampaignCreateContactStepInput, type ActiveCampaignCreateContactStepOutput, type AddSubtitlesToVideoStepInput, type AddSubtitlesToVideoStepOutput, type AgentInfo, type AgentOptions, type AirtableCreateUpdateRecordStepInput, type AirtableCreateUpdateRecordStepOutput, type AirtableDeleteRecordStepInput, type AirtableDeleteRecordStepOutput, type AirtableGetRecordStepInput, type AirtableGetRecordStepOutput, type AirtableGetTableRecordsStepInput, type AirtableGetTableRecordsStepOutput, 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 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 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 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 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 LogicStepInput, type LogicStepOutput, type MakeDotComRunScenarioStepInput, type MakeDotComRunScenarioStepOutput, 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 QueryAppDatabaseStepInput, type QueryAppDatabaseStepOutput, type QueryDataSourceStepInput, type QueryDataSourceStepOutput, type QueryExternalDatabaseStepInput, type QueryExternalDatabaseStepOutput, 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 RunTaskResult, 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 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 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 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, auth, blockTypeAliases, dataSources, db, mindstudio as default, files, getRequestContext, mindstudio, monacoSnippets, prerender, reportIssue, resolveUser, runWithContext, stepMetadata, stream };

package/dist/index.js

@@ -2112,6 +2112,96 @@ function createFiles(call) {
   };
 }
 
+// src/datasources/source.ts
+import { createHash as createHash2 } from "crypto";
+var DataSource = class {
+  constructor(_slug, _call) {
+    this._slug = _slug;
+    this._call = _call;
+  }
+  get name() {
+    return this._slug;
+  }
+  /**
+   * Search the corpus.
+   *
+   * Returns chunks ranked by relevance, each with a citation. Searching a
+   * source that doesn't exist yet returns no results rather than throwing —
+   * code may name a corpus the build hasn't populated.
+   */
+  async search(query, options) {
+    const { results } = await this._call("search", {
+      slug: this._slug,
+      query,
+      ...options?.topK !== void 0 ? { topK: options.topK } : {},
+      ...options?.scoreThreshold !== void 0 ? { scoreThreshold: options.scoreThreshold } : {},
+      ...options?.rerank !== void 0 ? { rerank: options.rerank } : {},
+      ...options?.hybrid !== void 0 ? { hybrid: options.hybrid } : {}
+    });
+    return { results: results ?? [] };
+  }
+  /**
+   * Add a document to the corpus.
+   *
+   * Returns as soon as the document is queued — extraction and embedding run
+   * in the background and take a while, so poll {@link documents} for status
+   * rather than assuming the content is searchable on return.
+   *
+   * **Adding the same bytes twice is free.** Documents are content-addressed,
+   * so a re-add is a no-op when this source has already processed those exact
+   * bytes under its current configuration. Reconfiguring the source is what
+   * makes a re-add do work again — and that is an explicit, owner-triggered
+   * migration, never something a deploy causes.
+   */
+  async add(content, options) {
+    const bytes = typeof content === "string" ? Buffer.from(content) : Buffer.from(content);
+    return this._call("add", {
+      slug: this._slug,
+      filename: options.filename,
+      ...options.contentType ? { contentType: options.contentType } : {},
+      body: bytes.toString("base64")
+    });
+  }
+  /** Every document in the corpus, with ingest status. */
+  async documents() {
+    const { documents } = await this._call("documents", { slug: this._slug });
+    return documents ?? [];
+  }
+  /** Remove a document and its vectors. */
+  async remove(documentId) {
+    await this._call("remove", { slug: this._slug, documentId });
+  }
+  /**
+   * Create the data source if it doesn't exist yet.
+   *
+   * Rarely needed — `add` and `search` both handle a missing source. Useful
+   * when you want it to exist (and appear in the dashboard) before any
+   * document has been added.
+   */
+  async ensure(name) {
+    await this._call("ensure", {
+      slug: this._slug,
+      ...name ? { name } : {}
+    });
+  }
+  /**
+   * @internal Content hash of some bytes, matching what the server computes.
+   * Exposed for callers that want to check whether they already added a file.
+   */
+  static contentHash(content) {
+    return createHash2("sha256").update(Buffer.from(content)).digest("hex");
+  }
+};
+
+// src/datasources/index.ts
+function createDataSources(call) {
+  return {
+    defineDataSource(name) {
+      return new DataSource(name, call);
+    }
+  };
+}
+
 // src/generated/metadata.ts
 var stepMetadata = {
   "activeCampaignAddNote": {
@@ -4126,6 +4216,7 @@ var MindStudioAgent = class {
   _db;
   /** @internal Cached Files namespace instance (lazy; no context hydration needed). */
   _files;
+  _dataSources;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -5017,12 +5108,47 @@ var MindStudioAgent = class {
   get files() {
     return this._files ??= createFiles(this._filesRequest.bind(this));
   }
+  /**
+   * Searchable document corpora.
+   *
+   * @example
+   * ```ts
+   * const Policies = agent.dataSources.defineDataSource('policies');
+   * const { results } = await Policies.search('what are the payment terms?');
+   * ```
+   */
+  get dataSources() {
+    return this._dataSources ??= createDataSources(
+      this._dataSourcesRequest.bind(this)
+    );
+  }
   /**
    * @internal Transport for the `files` namespace — POST /_internal/v2/files/<op>
    * with the raw hook token (mirrors `_executeDbBatch`).
    */
   async _filesRequest(op, body) {
-    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/files/${op}`;
+    return this._brokeredRequest("files", op, body, {
+      fallbackMessage: "File operation failed",
+      fallbackCode: "file_error"
+    });
+  }
+  /**
+   * @internal Transport for the `dataSources` namespace —
+   * POST /_internal/v2/datasources/<op> with the raw hook token.
+   */
+  async _dataSourcesRequest(op, body) {
+    return this._brokeredRequest("datasources", op, body, {
+      fallbackMessage: "Data source operation failed",
+      fallbackCode: "data_source_error"
+    });
+  }
+  /**
+   * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data
+   * planes. Factored out rather than copied per namespace so error handling
+   * can't drift between them.
+   */
+  async _brokeredRequest(namespace, op, body, errors) {
+    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/${namespace}/${op}`;
     const res = await fetch(url, {
       method: "POST",
       headers: {
@@ -5044,8 +5170,8 @@ var MindStudioAgent = class {
     }
     if (!res.ok) {
       const rawMsg = json?.errorMessage ?? (typeof json?.error === "string" ? json.error : json?.error?.message);
-      const message = typeof rawMsg === "string" ? rawMsg : `File operation failed: ${res.status} ${res.statusText}`;
-      const code = json?.errorString ?? json?.code ?? "file_error";
+      const message = typeof rawMsg === "string" ? rawMsg : `${errors.fallbackMessage}: ${res.status} ${res.statusText}`;
+      const code = json?.errorString ?? json?.code ?? errors.fallbackCode;
       throw new MindStudioError(message, code, res.status);
     }
     return json;
@@ -5726,6 +5852,16 @@ var files = new Proxy(
     }
   }
 );
+var dataSources = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const target = mindstudio.dataSources;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  }
+);
 var stream = (data) => mindstudio.stream(data);
 var resolveUser = (userId) => mindstudio.resolveUser(userId);
 var reportIssue = (input) => mindstudio.reportIssue(input);
@@ -5739,6 +5875,7 @@ export {
   Roles,
   auth,
   blockTypeAliases,
+  dataSources,
   db,
   index_default as default,
   files,