@almadar/integrations 2.29.0 → 2.31.0

package/dist/{store-eq1-GfDi.d.ts → store-BYRZDq9B.d.ts}

@@ -1,5 +1,5 @@
 import { ServiceParamsValue, ServiceParams, EntityRow } from '@almadar/core';
-import { f as IntegrationParamValue, g as IntegrationParams } from './BaseIntegration-C_5q54DM.js';
+import { f as IntegrationParamValue, g as IntegrationParams } from './BaseIntegration-BYlbMFlf.js';
 
 /** Scalar value admissible as a SQL bind parameter. */
 type DatabaseQueryParamValue = string | number | boolean | Date | null;
@@ -38,49 +38,68 @@ interface DatabaseDriver {
  */
 
 type GitHubActions = {
+    /** Clone a repository via the git CLI into a local target directory, using the configured token for auth. */
     cloneRepo: {
         params: {
+            /** HTTPS clone URL, e.g. https://github.com/owner/repo. Owner/repo are parsed from it when not preconfigured. */
             repoUrl: string;
+            /** Local directory to clone into. */
             targetDir: string;
+            /** Branch to check out after cloning; defaults to the repo's default branch. */
             branch?: string;
         };
         result: {
             message: string;
         };
     };
+    /** Create a new local branch via the git CLI in the configured working directory. */
     createBranch: {
         params: {
+            /** Name of the branch to create. */
             branchName: string;
+            /** Branch to branch from; defaults to the current branch. */
             baseBranch?: string;
         };
         result: {
             message: string;
         };
     };
+    /** Commit staged (or given) changes via the git CLI in the configured working directory. */
     commit: {
         params: {
+            /** Commit message. */
             message: string;
+            /** Specific files to commit; when omitted, all changes are committed. */
             files?: string[];
         };
         result: {
             message: string;
         };
     };
+    /** Push a local branch to the remote via the git CLI, using the configured token for auth. */
     push: {
         params: {
+            /** Branch name to push. */
             branchName: string;
+            /** Force-push (overwrites remote history); never set true in an agent context. */
             force?: boolean;
         };
         result: {
             message: string;
         };
     };
+    /** Open a pull request via the GitHub REST API. */
     createPR: {
         params: {
+            /** Pull request title. */
             title: string;
+            /** Pull request description body. */
             body: string;
+            /** Branch the PR merges into, e.g. main. */
             baseBranch: string;
+            /** Branch the PR merges from (the feature branch). */
             headBranch: string;
+            /** Open as a draft PR instead of ready-for-review. */
             draft?: boolean;
         };
         result: {
@@ -89,8 +108,10 @@ type GitHubActions = {
             title: string;
         };
     };
+    /** List review comments on a pull request via the GitHub REST API. */
     getPRComments: {
         params: {
+            /** Pull request number. */
             prNumber: number;
         };
         result: {
@@ -101,10 +122,14 @@ type GitHubActions = {
             }>;
         };
     };
+    /** List issues on the configured repository via the GitHub REST API. */
     listIssues: {
         params: {
+            /** Issue state filter: 'open', 'closed', or 'all'; defaults to open. */
             state?: string;
+            /** Only issues carrying all of these labels. */
             labels?: string[];
+            /** Page size for the GitHub API request. */
             per_page?: number;
         };
         result: {
@@ -115,8 +140,10 @@ type GitHubActions = {
             }>;
         };
     };
+    /** Fetch a single issue's details via the GitHub REST API. */
     getIssue: {
         params: {
+            /** Issue number. */
             issueNumber: number;
         };
         result: {
@@ -126,11 +153,16 @@ type GitHubActions = {
             state: string;
         };
     };
+    /** Read a file's content from a repository at a given ref (declared intent — dispatch is being wired). */
     getFile: {
         params: {
+            /** Repository owner (user or org). */
             owner: string;
+            /** Repository name. */
             repo: string;
+            /** File path within the repository. */
             path: string;
+            /** Branch, tag, or commit SHA to read from; defaults to the default branch. */
             ref?: string;
         };
         result: {
@@ -140,12 +172,18 @@ type GitHubActions = {
             size: number;
         };
     };
+    /** List commits on a repository, optionally filtered by file path (declared intent — dispatch is being wired). */
     listCommits: {
         params: {
+            /** Repository owner (user or org). */
             owner: string;
+            /** Repository name. */
             repo: string;
+            /** Only commits touching this file path. */
             path?: string;
+            /** Branch, tag, or commit SHA to start from; defaults to the default branch. */
             ref?: string;
+            /** Page size for the GitHub API request. */
             per_page?: number;
         };
         result: {
@@ -157,12 +195,18 @@ type GitHubActions = {
             }>;
         };
     };
+    /** Open a new issue on a repository (declared intent — dispatch is being wired). */
     createIssue: {
         params: {
+            /** Repository owner (user or org). */
             owner: string;
+            /** Repository name. */
             repo: string;
+            /** Issue title. */
             title: string;
+            /** Issue body/description. */
             body?: string;
+            /** Labels to apply to the new issue. */
             labels?: string[];
         };
         result: {
@@ -173,10 +217,17 @@ type GitHubActions = {
     };
 };
 type StripeActions = {
+    /**
+     * Create a Stripe PaymentIntent for a one-off charge.
+     * @synonyms charge, pay
+     */
     createPaymentIntent: {
         params: {
+            /** Charge amount in the currency's smallest unit (e.g. cents for USD). */
             amount: number;
+            /** ISO 4217 currency code, e.g. usd. */
             currency: string;
+            /** Arbitrary key-value tags attached to the PaymentIntent (string values only). */
             metadata?: Record<string, string>;
         };
         result: {
@@ -187,8 +238,10 @@ type StripeActions = {
             currency: string;
         };
     };
+    /** Confirm a previously created PaymentIntent, attempting to complete the charge. */
     confirmPayment: {
         params: {
+            /** The PaymentIntent id returned by createPaymentIntent. */
             paymentIntentId: string;
         };
         result: {
@@ -196,9 +249,12 @@ type StripeActions = {
             status: string;
         };
     };
+    /** Refund a charged PaymentIntent, in full or in part. */
     refund: {
         params: {
+            /** The PaymentIntent id to refund. */
             paymentIntentId: string;
+            /** Amount to refund in the currency's smallest unit; omit for a full refund. */
             amount?: number;
         };
         result: {
@@ -209,12 +265,18 @@ type StripeActions = {
     };
 };
 type LLMIntegrationActions = {
+    /** Generate free-form text from a prompt via the configured LLM provider (default 'You are a helpful assistant.' system prompt). */
     generate: {
         params: {
+            /** The user/task prompt sent to the model. */
             userPrompt: string;
+            /** System prompt steering the model's behavior; defaults to a generic assistant prompt. */
             systemPrompt?: string;
+            /** Model id override; when set, a fresh client is built for this call instead of the shared one. */
             model?: string;
+            /** Sampling temperature (0-1ish, provider-dependent); higher is more random. */
             temperature?: number;
+            /** Maximum tokens to generate; defaults to 1024. */
             maxTokens?: number;
         };
         result: {
@@ -227,10 +289,14 @@ type LLMIntegrationActions = {
             };
         };
     };
+    /** Classify text into exactly one of a caller-supplied category list, with a confidence score and reasoning. */
     classify: {
         params: {
+            /** Text to classify. */
             text: string;
+            /** Closed set of category labels the model must choose from. */
             categories: string[];
+            /** Model id override. */
             model?: string;
         };
         result: {
@@ -239,19 +305,28 @@ type LLMIntegrationActions = {
             reasoning: string;
         };
     };
+    /** Extract structured data from text according to a JSON-schema-shaped description; returned data is not validated against the schema. */
     extract: {
         params: {
+            /** Source text to extract data from. */
             text: string;
+            /** JSON-schema-like description of the fields to extract; passed to the model as a prompt, not enforced structurally. */
             schema: IntegrationParams;
+            /** Model id override. */
             model?: string;
         };
         result: IntegrationParams;
     };
+    /** Summarize text, optionally constrained by length and style, returning a summary plus key points. */
     summarize: {
         params: {
+            /** Text to summarize. */
             text: string;
+            /** Target maximum summary length in words. */
             maxLength?: number;
+            /** Summary style: 'bullet' for bullet points, 'detailed' for thorough, otherwise concise. */
             style?: string;
+            /** Model id override. */
             model?: string;
         };
         result: {
@@ -259,9 +334,12 @@ type LLMIntegrationActions = {
             keyPoints: string[];
         };
     };
+    /** Generate embedding vectors for an array of texts via the configured embedding model (default baai/bge-base-en-v1.5 on OpenRouter, independent of the chat provider). */
     embed: {
         params: {
+            /** Texts to embed, one vector per entry, in order. */
             texts: string[];
+            /** Embedding model id override. */
             model?: string;
         };
         result: {
@@ -270,9 +348,12 @@ type LLMIntegrationActions = {
     };
 };
 type MLActions = {
+    /** Run inference against a deployed model-serving orbital by posting an INFER event and reading the prediction back out of the emitted INFERRED result; may cold-start (up to 60s default timeout). */
     infer: {
         params: {
+            /** Checkpoint or model identifier the serving orbital resolves. */
             model: string;
+            /** JSON-safe model input payload. */
             input: ServiceParamsValue;
         };
         result: {
@@ -283,10 +364,14 @@ type MLActions = {
     };
 };
 type YouTubeActions = {
+    /** Search YouTube via the Data API and return matching video snippets. */
     search: {
         params: {
+            /** Search query text. */
             query: string;
+            /** Maximum number of results; defaults to 10. */
             maxResults?: number;
+            /** Resource type filter passed to the Data API (e.g. 'video', 'channel', 'playlist'). */
             type?: string;
         };
         result: Array<{
@@ -296,8 +381,10 @@ type YouTubeActions = {
             description: string;
         }>;
     };
+    /** Fetch a video's snippet and statistics via the YouTube Data API. */
     getVideo: {
         params: {
+            /** YouTube video id. */
             videoId: string;
         };
         result: {
@@ -307,8 +394,10 @@ type YouTubeActions = {
             likeCount: string;
         };
     };
+    /** Fetch a channel's snippet and statistics via the YouTube Data API. */
     getChannel: {
         params: {
+            /** YouTube channel id. */
             channelId: string;
         };
         result: {
@@ -319,10 +408,17 @@ type YouTubeActions = {
     };
 };
 type TwilioActions = {
+    /**
+     * Send an SMS message via Twilio.
+     * @synonyms text message, text
+     */
     sendSMS: {
         params: {
+            /** Destination phone number, E.164 format. */
             to: string;
+            /** Message text. */
             body: string;
+            /** Sender phone number; defaults to TWILIO_PHONE_NUMBER. */
             from?: string;
         };
         result: {
@@ -330,9 +426,12 @@ type TwilioActions = {
             status: string;
         };
     };
+    /** Send a WhatsApp message via Twilio, using the configured phone number as sender on both ends. */
     sendWhatsApp: {
         params: {
+            /** Destination phone number, E.164 format (sent as whatsapp:number). */
             to: string;
+            /** Message text. */
             body: string;
         };
         result: {
@@ -342,14 +441,20 @@ type TwilioActions = {
     };
 };
 type EmailActions = {
+    /** Send a transactional email via the configured provider (SendGrid or Resend). */
     send: {
         params: {
+            /** Recipient email address. */
             to: string;
+            /** Email subject line. */
             subject: string;
+            /** Plain-text (or HTML, if `htmlBody` is absent) body content. */
             body: string;
+            /** Sender address; defaults to FROM_EMAIL. */
             from?: string;
             /** HTML content; when present `body` becomes the plain-text alternative. */
             htmlBody?: string;
+            /** Reply-To address. */
             replyTo?: string;
             /** Provider template reference (SendGrid dynamic templates; Resend rejects it loudly). */
             templateId?: string;
@@ -361,11 +466,16 @@ type EmailActions = {
     };
 };
 type WebhookActions = {
+    /** POST a JSON event notification to an external URL, HMAC-SHA256-signed when a secret is configured; 5xx responses retry, 4xx do not. */
     send: {
         params: {
+            /** Destination URL to POST to. */
             url: string;
+            /** Event name, carried in the body and the X-Almadar-Event header. */
             event: string;
+            /** Event payload; defaults to an empty object. */
             payload?: Record<string, string>;
+            /** Per-call HMAC signing secret, overriding WEBHOOK_SIGNING_SECRET. */
             secret?: string;
         };
         result: {
@@ -376,8 +486,10 @@ type WebhookActions = {
     };
 };
 type PushActions = {
+    /** Send a VAPID-signed Web Push notification to a browser PushSubscription endpoint. */
     send: {
         params: {
+            /** Browser PushSubscription: endpoint URL plus the p256dh/auth encryption keys. */
             subscription: {
                 endpoint: string;
                 keys: {
@@ -385,25 +497,36 @@ type PushActions = {
                     auth: string;
                 };
             };
+            /** Notification title. */
             title: string;
+            /** Notification body text. */
             body: string;
+            /** URL to open when the notification is clicked. */
             url?: string;
+            /** Notification icon URL. */
             icon?: string;
         };
         result: {
             statusCode: number;
             ok: boolean;
+            /** True on a 404/410 push-service response — the subscription is gone and must be pruned, never retried. */
             expired: boolean;
         };
     };
 };
 type CalendarActions = {
+    /** List events on a Google Calendar; pass `syncToken` for incremental sync instead of a time window (the API rejects combining them). */
     listEvents: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID (or 'primary'). */
             calendarId?: string;
+            /** ISO start of the time window (ignored when `syncToken` is set). */
             timeMin?: string;
+            /** ISO end of the time window (ignored when `syncToken` is set). */
             timeMax?: string;
+            /** Incremental-sync token from a previous call's `nextSyncToken`; supersedes timeMin/timeMax. */
             syncToken?: string;
+            /** Maximum events to return; defaults to 250. */
             maxResults?: number;
         };
         result: {
@@ -417,17 +540,26 @@ type CalendarActions = {
                 status: string;
                 updated: string;
             }>;
+            /** Token to pass as `syncToken` on the next call; null when incremental sync isn't available for this response. */
             nextSyncToken: string | null;
         };
     };
+    /** Create a calendar event; an all-day event uses a 10-char (YYYY-MM-DD) start with no `end`/`durationMinutes`, defaulting to the next day. */
     createEvent: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID. */
             calendarId?: string;
+            /** Event title. */
             summary: string;
+            /** Event description. */
             description?: string;
+            /** Event location text. */
             location?: string;
+            /** ISO start (10 chars = all-day date, longer = dateTime). */
             start: string;
+            /** ISO end; if omitted, derived from `durationMinutes` or the all-day next-day convention. */
             end?: string;
+            /** Duration in minutes used to derive `end` when `end` is omitted (non-all-day events only). */
             durationMinutes?: number;
         };
         result: {
@@ -436,14 +568,22 @@ type CalendarActions = {
             htmlLink: string;
         };
     };
+    /** Patch an existing event's fields; only fields present in params are changed. */
     updateEvent: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID. */
             calendarId?: string;
+            /** Id of the event to update. */
             eventId: string;
+            /** New event title. */
             summary?: string;
+            /** New event description. */
             description?: string;
+            /** New event location text. */
             location?: string;
+            /** New ISO start. */
             start?: string;
+            /** New ISO end. */
             end?: string;
         };
         result: {
@@ -451,9 +591,12 @@ type CalendarActions = {
             status: string;
         };
     };
+    /** Delete a calendar event. */
     deleteEvent: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID. */
             calendarId?: string;
+            /** Id of the event to delete. */
             eventId: string;
         };
         result: {
@@ -461,10 +604,14 @@ type CalendarActions = {
             deleted: boolean;
         };
     };
+    /** Query busy time blocks on a calendar within a window. */
     freeBusy: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID. */
             calendarId?: string;
+            /** ISO start of the query window. */
             timeMin: string;
+            /** ISO end of the query window. */
             timeMax: string;
         };
         result: {
@@ -474,11 +621,16 @@ type CalendarActions = {
             }>;
         };
     };
+    /** Register a push-notification channel for calendar change events (Google Calendar API watch). */
     watch: {
         params: {
+            /** Calendar id; defaults to GOOGLE_CALENDAR_ID. */
             calendarId?: string;
+            /** Caller-chosen id identifying this notification channel. */
             channelId: string;
+            /** HTTPS callback URL Google POSTs change notifications to. */
             address: string;
+            /** Requested channel time-to-live in seconds. */
             ttlSeconds?: number;
         };
         result: {
@@ -487,9 +639,12 @@ type CalendarActions = {
             expiration: string;
         };
     };
+    /** Stop an active watch channel, ending calendar change notifications. */
     stopWatch: {
         params: {
+            /** The channel id from the corresponding `watch` call. */
             channelId: string;
+            /** The resourceId returned by the corresponding `watch` call. */
             resourceId: string;
         };
         result: {
@@ -498,10 +653,14 @@ type CalendarActions = {
     };
 };
 type DriveActions = {
+    /** List non-trashed files in a Google Drive folder, optionally filtered by a Drive API query clause. */
     listFiles: {
         params: {
+            /** Restrict to files whose parents include this folder id. */
             folderId?: string;
+            /** Extra Drive API query clause, ANDed with the folder/trashed filters. */
             query?: string;
+            /** Maximum files to return; defaults to 100. */
             maxResults?: number;
         };
         result: {
@@ -515,8 +674,10 @@ type DriveActions = {
             }>;
         };
     };
+    /** Download a file's content, base64-encoded. */
     getFile: {
         params: {
+            /** Drive file id. */
             fileId: string;
         };
         result: {
@@ -527,11 +688,19 @@ type DriveActions = {
             size: number;
         };
     };
+    /**
+     * Upload a file to Drive; writes go through the user OAuth client when configured (service-account uploads have no storage quota on personal accounts).
+     * @synonyms upload file
+     */
     uploadFile: {
         params: {
+            /** File name to create. */
             name: string;
+            /** File content as a base64 data URL (data:mime;base64,...) or raw base64/plain text. */
             content: string;
+            /** MIME type; inferred from a data URL when omitted. */
             mimeType?: string;
+            /** Parent folder id; defaults to GOOGLE_DRIVE_FOLDER_ID. */
             folderId?: string;
         };
         result: {
@@ -540,9 +709,12 @@ type DriveActions = {
             webViewLink: string;
         };
     };
+    /** Create a new Drive folder. */
     createFolder: {
         params: {
+            /** Folder name to create. */
             name: string;
+            /** Parent folder id; defaults to GOOGLE_DRIVE_FOLDER_ID. */
             parentId?: string;
         };
         result: {
@@ -550,10 +722,14 @@ type DriveActions = {
             name: string;
         };
     };
+    /** Grant a user permission on a Drive file. */
     shareFile: {
         params: {
+            /** Drive file id. */
             fileId: string;
+            /** Email address of the grantee. */
             email: string;
+            /** Permission level; defaults to 'reader'. */
             role?: 'reader' | 'writer' | 'commenter';
         };
         result: {
@@ -563,12 +739,15 @@ type DriveActions = {
     };
 };
 type MetaAdsActions = {
+    /** Fetch total ad spend, impressions, and clicks for an account over a date range via the Meta Graph API Marketing Insights endpoint (read-only). */
     getSpend: {
         params: {
+            /** Ad account id (with or without the `act_` prefix); defaults to META_AD_ACCOUNT_ID. */
             accountId?: string;
+            /** Range start date (YYYY-MM-DD). */
             since: string;
+            /** Range end date (YYYY-MM-DD). */
             until: string;
-            clientTag?: string;
         };
         result: {
             spend: number;
@@ -577,9 +756,12 @@ type MetaAdsActions = {
             clicks: number;
         };
     };
+    /** List campaigns on an ad account via the Meta Graph API (read-only); dailyBudget is converted from Meta's minor-unit reporting. */
     listCampaigns: {
         params: {
+            /** Ad account id (with or without the `act_` prefix); defaults to META_AD_ACCOUNT_ID. */
             accountId?: string;
+            /** Filter by campaign effective_status (e.g. 'ACTIVE', 'PAUSED'). */
             status?: string;
         };
         result: {
@@ -593,8 +775,10 @@ type MetaAdsActions = {
     };
 };
 type AccountingActions = {
+    /** Shape invoice rows into an import-ready CSV export (no accounting-vendor connection — generic column set). */
     exportInvoices: {
         params: {
+            /** Invoice rows to export, in column order id/number/customer/issuedAt/dueAt/currency/net/tax/gross/status. */
             invoices: Array<{
                 id: string;
                 number: string;
@@ -607,6 +791,7 @@ type AccountingActions = {
                 gross: number;
                 status: string;
             }>;
+            /** Export format; only 'csv' is currently supported. */
             format?: 'csv';
         };
         result: {
@@ -615,8 +800,10 @@ type AccountingActions = {
             count: number;
         };
     };
+    /** Shape journal entry rows into an import-ready CSV export. */
     exportJournal: {
         params: {
+            /** Journal entry rows to export, in column order date/account/description/debit/credit/reference. */
             entries: Array<{
                 date: string;
                 account: string;
@@ -625,6 +812,7 @@ type AccountingActions = {
                 credit: number;
                 reference: string;
             }>;
+            /** Export format; only 'csv' is currently supported. */
             format?: 'csv';
         };
         result: {
@@ -635,10 +823,14 @@ type AccountingActions = {
     };
 };
 type BankingActions = {
+    /** Start a GoCardless Bank Account Data requisition (bank-connection consent flow); the returned `link` is where the end user authorizes access. */
     createRequisition: {
         params: {
+            /** GoCardless institution id (the bank to connect). */
             institutionId: string;
+            /** URL GoCardless redirects the user to after consent. */
             redirectUrl: string;
+            /** Caller-chosen reference to correlate the requisition. */
             reference?: string;
         };
         result: {
@@ -646,18 +838,24 @@ type BankingActions = {
             link: string;
         };
     };
+    /** List account ids linked under a completed requisition. */
     listAccounts: {
         params: {
+            /** Requisition id from createRequisition. */
             requisitionId: string;
         };
         result: {
             accounts: string[];
         };
     };
+    /** List booked transactions on a linked bank account, optionally filtered by date range. */
     listTransactions: {
         params: {
+            /** GoCardless account id. */
             accountId: string;
+            /** Only transactions booked on/after this date (YYYY-MM-DD). */
             dateFrom?: string;
+            /** Only transactions booked on/before this date (YYYY-MM-DD). */
             dateTo?: string;
         };
         result: {
@@ -673,12 +871,18 @@ type BankingActions = {
     };
 };
 type EsignActions = {
+    /** Send a document for e-signature via DocuSign; accepts the document content as a data URL or raw base64. */
     sendEnvelope: {
         params: {
+            /** Signer's email address. */
             recipientEmail: string;
+            /** Signer's display name. */
             recipientName: string;
+            /** Document file name (its extension also picks the DocuSign fileExtension). */
             documentName: string;
+            /** Document content as a base64 data URL or raw base64. */
             documentContent: string;
+            /** Envelope email subject; defaults to "Please sign: " + documentName. */
             emailSubject?: string;
         };
         result: {
@@ -686,8 +890,10 @@ type EsignActions = {
             status: string;
         };
     };
+    /** Poll a DocuSign envelope's signing status. */
     getEnvelopeStatus: {
         params: {
+            /** DocuSign envelope id from sendEnvelope. */
             envelopeId: string;
         };
         result: {
@@ -695,8 +901,10 @@ type EsignActions = {
             completedAt: string;
         };
     };
+    /** Download the combined signed document(s) for a completed envelope, base64-encoded PDF. */
     downloadDocument: {
         params: {
+            /** DocuSign envelope id. */
             envelopeId: string;
         };
         result: {
@@ -706,11 +914,16 @@ type EsignActions = {
     };
 };
 type DockerActions = {
+    /** Simulate building a container image (in-memory backend — no real Docker daemon/SDK; a real build is not yet implemented). */
     build: {
         params: {
+            /** Image tag to build, e.g. myapp:latest. */
             tag: string;
+            /** Dockerfile path; defaults to 'Dockerfile'. */
             dockerfile?: string;
+            /** Build context directory; defaults to '.'. */
             context?: string;
+            /** Build-time --build-arg values. */
             buildArgs?: Record<string, string>;
         };
         result: {
@@ -720,20 +933,27 @@ type DockerActions = {
             buildTime: number;
         };
     };
+    /** Simulate starting a container from an image (in-memory backend). */
     run: {
         params: {
+            /** Image to run (as built/tagged by the `build` action, or an arbitrary name). */
             image: string;
+            /** Container name; auto-generated when omitted. */
             name?: string;
+            /** Host/container port mappings. */
             ports?: Array<{
                 host: number;
                 container: number;
                 protocol?: string;
             }>;
+            /** Environment variables set inside the container. */
             env?: Record<string, string>;
+            /** Host/container path mounts. */
             volumes?: Array<{
                 host: string;
                 container: string;
             }>;
+            /** Override command run inside the container. */
             command?: string;
         };
         result: {
@@ -747,8 +967,10 @@ type DockerActions = {
             }>;
         };
     };
+    /** Stop a running (or paused) simulated container. */
     stop: {
         params: {
+            /** Container id, or a unique id prefix. */
             containerId: string;
         };
         result: {
@@ -757,9 +979,12 @@ type DockerActions = {
             stoppedAt: number;
         };
     };
+    /** Remove a simulated container; fails if it is running unless `force` is set. */
     remove: {
         params: {
+            /** Container id, or a unique id prefix. */
             containerId: string;
+            /** Remove even if the container is currently running. */
             force?: boolean;
         };
         result: {
@@ -767,10 +992,14 @@ type DockerActions = {
             removed: boolean;
         };
     };
+    /** Fetch generated log lines for a simulated container. */
     logs: {
         params: {
+            /** Container id, or a unique id prefix. */
             containerId: string;
+            /** Number of most-recent lines to return; defaults to 100. */
             tail?: number;
+            /** Only lines timestamped at/after this ISO time. */
             since?: string;
         };
         result: {
@@ -779,8 +1008,10 @@ type DockerActions = {
             lineCount: number;
         };
     };
+    /** Fetch a simulated container's current status and metadata. */
     status: {
         params: {
+            /** Container id, or a unique id prefix. */
             containerId: string;
         };
         result: {
@@ -798,9 +1029,12 @@ type DockerActions = {
             stoppedAt: number | null;
         };
     };
+    /** List simulated containers; by default only running ones (like `docker ps`). */
     list: {
         params: {
+            /** Include stopped/exited containers, not just running ones. */
             all?: boolean;
+            /** Filter by a `key` or `key=value` label match. */
             filterByLabel?: string;
         };
         result: {
@@ -821,20 +1055,32 @@ type DockerActions = {
     };
 };
 type StorageActions = {
+    /**
+     * Upload an object to an S3-compatible bucket (real S3/R2/MinIO backend when storage credentials are configured, in-memory dev fallback otherwise — refused in production). Admits either the canonical `key`+`content` pair or the file-form `file` payload (UploadDropZone's `{ name, size, type, content }` shape); when `file` is present its `key`/`content` are derived from it.
+     * @synonyms upload file, upload object
+     */
     upload: {
         params: {
+            /** Target bucket; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Object key to store under (canonical shape); ignored when `file` is present. */
             key?: string;
+            /** Object content as a base64 data URL, raw base64, or plain text (canonical shape); ignored when `file` is present. */
             content?: string;
+            /** MIME type override for the canonical shape; inferred from a data URL when omitted. */
             contentType?: string;
+            /** File-form upload payload (as emitted by UploadDropZone); `content` is a base64 data URL. */
             file?: {
                 name: string;
                 size: number;
                 type: string;
                 content?: string;
             };
+            /** Object ACL — 'public' produces a public URL, otherwise the URL is signed/private. */
             acl?: 'public' | 'private';
+            /** Reject the upload if the file-form payload's declared size exceeds this many bytes. */
             maxSize?: number;
+            /** Arbitrary metadata stored alongside the object (in-memory backend only). */
             metadata?: IntegrationParams;
         };
         result: {
@@ -846,16 +1092,21 @@ type StorageActions = {
             url: string;
         };
     };
+    /** Upload a whole UploadDropZone batch in one call, one item per file — the FSM-friendly shape for bulk-persisting uploaded-file rows. */
     uploadMany: {
         params: {
+            /** Target bucket; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Files to upload, in UploadDropZone's `{ name, size, type, content }` shape. */
             files: Array<{
                 name: string;
                 size: number;
                 type: string;
                 content?: string;
             }>;
+            /** Object ACL applied to every file in the batch. */
             acl?: 'public' | 'private';
+            /** Reject any file whose declared size exceeds this many bytes. */
             maxSize?: number;
         };
         result: {
@@ -870,9 +1121,12 @@ type StorageActions = {
             count: number;
         };
     };
+    /** Download an object's content, base64-encoded. */
     download: {
         params: {
+            /** Bucket the object lives in; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Object key. */
             key: string;
         };
         result: {
@@ -882,11 +1136,16 @@ type StorageActions = {
             metadata: IntegrationParams;
         };
     };
+    /** List object keys in a bucket, optionally prefix-filtered, one page at a time. */
     list: {
         params: {
+            /** Bucket to list; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Only keys starting with this prefix. */
             prefix?: string;
+            /** Maximum keys per page; defaults to 1000. */
             maxKeys?: number;
+            /** Pagination token from a previous call's `nextToken`. */
             continuationToken?: string;
         };
         result: {
@@ -896,23 +1155,32 @@ type StorageActions = {
                 lastModified: number;
             }>;
             truncated: boolean;
+            /** Present iff `truncated` — pass back as `continuationToken` for the next page. */
             nextToken?: string;
         };
     };
+    /** Delete an object from a bucket. */
     delete: {
         params: {
+            /** Bucket the object lives in; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Object key to delete. */
             key: string;
         };
         result: {
             deleted: boolean;
         };
     };
+    /** Generate a time-limited pre-signed URL for direct GET or PUT access to an object. */
     getSignedUrl: {
         params: {
+            /** Bucket the object lives in; defaults to STORAGE_BUCKET. */
             bucket: string;
+            /** Object key. */
             key: string;
+            /** URL validity window in seconds; defaults to 3600. */
             expiresIn?: number;
+            /** Whether the URL authorizes a read or a write; defaults to 'get'. */
             operation?: 'get' | 'put';
         };
         result: {
@@ -922,11 +1190,16 @@ type StorageActions = {
     };
 };
 type QueueActions = {
+    /** Add a job to an in-memory job queue, ordered by priority (higher first) among ready jobs. */
     enqueue: {
         params: {
+            /** Queue name. */
             queue: string;
+            /** Arbitrary job payload. */
             payload: ServiceParams;
+            /** Delay before the job becomes eligible for dequeue, in milliseconds. */
             delay?: number;
+            /** Priority — higher values are dequeued before lower ones. */
             priority?: number;
         };
         result: {
@@ -934,8 +1207,10 @@ type QueueActions = {
             position: number;
         };
     };
+    /** Pop the highest-priority pending job whose delay has elapsed, marking it 'processing'; returns null if none is ready. */
     dequeue: {
         params: {
+            /** Queue name. */
             queue: string;
         };
         result: {
@@ -947,8 +1222,10 @@ type QueueActions = {
             } | null;
         };
     };
+    /** Look up a job's current status by id. */
     status: {
         params: {
+            /** Job id from enqueue. */
             jobId: string;
         };
         result: {
@@ -961,34 +1238,44 @@ type QueueActions = {
             } | null;
         };
     };
+    /** Mark a 'processing' job completed and store its result; no-op (returns false) if the job isn't in 'processing' state. */
     complete: {
         params: {
+            /** Job id. */
             jobId: string;
+            /** Result payload to attach to the job. */
             result?: ServiceParams;
         };
         result: {
             completed: boolean;
         };
     };
+    /** Mark a 'processing' job failed; no-op (returns false) if the job isn't in 'processing' state. */
     fail: {
         params: {
+            /** Job id. */
             jobId: string;
+            /** Failure reason to attach to the job. */
             error?: string;
         };
         result: {
             failed: boolean;
         };
     };
+    /** Remove a 'pending' job from its queue; no-op (returns false) once it has been dequeued. */
     cancel: {
         params: {
+            /** Job id. */
             jobId: string;
         };
         result: {
             cancelled: boolean;
         };
     };
+    /** Count pending and processing jobs in a queue. */
     size: {
         params: {
+            /** Queue name. */
             queue: string;
         };
         result: {
@@ -999,35 +1286,46 @@ type QueueActions = {
     };
 };
 type RedisActions = {
+    /** Read a key's value from the in-memory cache; returns null (as `value`) if absent or expired. */
     get: {
         params: {
+            /** Cache key. */
             key: string;
         };
         result: {
             value: ServiceParams;
         };
     };
+    /** Write a key's value, optionally with an expiry. */
     set: {
         params: {
+            /** Cache key. */
             key: string;
+            /** Value to store. */
             value: ServiceParams;
+            /** Time-to-live in seconds; omit for no expiry. */
             ttl?: number;
         };
         result: {
             ok: boolean;
         };
     };
+    /** Delete a key. */
     delete: {
         params: {
+            /** Cache key. */
             key: string;
         };
         result: {
             deleted: boolean;
         };
     };
+    /** Acquire a mutex on a key; fails (returns acquired:false) if another lock on the key is still alive. */
     lock: {
         params: {
+            /** Lock key. */
             key: string;
+            /** Lock time-to-live in milliseconds; defaults to 30000 (30s). */
             ttl?: number;
         };
         result: {
@@ -1035,44 +1333,58 @@ type RedisActions = {
             lockId: string;
         };
     };
+    /** Release a lock; only succeeds when `lockId` matches the current holder. */
     unlock: {
         params: {
+            /** Lock key. */
             key: string;
+            /** Lock id returned by the corresponding `lock` call. */
             lockId: string;
         };
         result: {
             released: boolean;
         };
     };
+    /** Atomically add to a numeric key's value (creating it at 0 if absent), preserving any existing TTL. */
     increment: {
         params: {
+            /** Cache key. */
             key: string;
+            /** Amount to add; defaults to 1 (can be negative to decrement). */
             by?: number;
         };
         result: {
             value: number;
         };
     };
+    /** Set (or reset) a key's expiry; no-op (returns set:false) if the key doesn't exist or is already expired. */
     expire: {
         params: {
+            /** Cache key. */
             key: string;
+            /** New time-to-live in seconds. */
             ttl: number;
         };
         result: {
             set: boolean;
         };
     };
+    /** Publish a message to a channel; delivered synchronously to in-process subscriber callbacks only. */
     publish: {
         params: {
+            /** Channel name. */
             channel: string;
+            /** Message payload. */
             message: ServiceParams;
         };
         result: {
             receivers: number;
         };
     };
+    /** Register interest in a channel; does not itself wire a callback (that happens at a higher-level API). */
     subscribe: {
         params: {
+            /** Channel name. */
             channel: string;
         };
         result: {
@@ -1081,10 +1393,14 @@ type RedisActions = {
     };
 };
 type OAuthActions = {
+    /** Build the provider authorization URL (PKCE + state) for an OAuth/OIDC login redirect; real OIDC discovery when OAUTH_CLIENT_ID/SECRET are configured, an in-memory mock otherwise. */
     authorize: {
         params: {
+            /** Identity provider; OIDC issuer defaults to Google unless OIDC_ISSUER_URL overrides it. */
             provider: 'google' | 'github' | 'auth0';
+            /** OAuth scopes to request. */
             scopes: string[];
+            /** Callback URL the provider redirects back to after consent. */
             redirectUri: string;
         };
         result: {
@@ -1092,9 +1408,12 @@ type OAuthActions = {
             state: string;
         };
     };
+    /** Exchange an authorization code for tokens, consuming the one-time-use `state` from the matching `authorize` call. */
     token: {
         params: {
+            /** Authorization code from the provider's redirect callback. */
             code: string;
+            /** The `state` value returned by `authorize`. */
             state: string;
         };
         result: {
@@ -1104,8 +1423,10 @@ type OAuthActions = {
             tokenType: 'bearer';
         };
     };
+    /** Exchange a refresh token for a new access token. */
     refresh: {
         params: {
+            /** Refresh token from a prior `token` call. */
             refreshToken: string;
         };
         result: {
@@ -1113,16 +1434,20 @@ type OAuthActions = {
             expiresIn: number;
         };
     };
+    /** Revoke an access or refresh token. */
     revoke: {
         params: {
+            /** The access or refresh token to revoke. */
             token: string;
         };
         result: {
             revoked: boolean;
         };
     };
+    /** Fetch the authenticated user's profile claims for an access token. */
     userinfo: {
         params: {
+            /** Access token from a prior `token`/`refresh` call. */
             accessToken: string;
         };
         result: {
@@ -1134,8 +1459,10 @@ type OAuthActions = {
     };
 };
 type CredentialsActions = {
+    /** List declared credentials and their masked (last-4) configuration status; open to any caller. */
     list: {
         params: {
+            /** Restrict the listing to one service's declared credentials; omit for all services. */
             service?: string;
         };
         result: {
@@ -1151,10 +1478,14 @@ type CredentialsActions = {
             }>;
         };
     };
+    /** Save a credential value into the hosted store; the env var must be one declared for the service (or a well-formed connection-ref name for `database`). Admin/owner role required. */
     set: {
         params: {
+            /** Integration name the credential belongs to. */
             service: string;
+            /** Declared env-var name being set. */
             envVar: string;
+            /** Secret value to store; never logged. */
             value: string;
         };
         result: {
@@ -1164,17 +1495,22 @@ type CredentialsActions = {
             last4: string;
         };
     };
+    /** Delete a stored credential from the hosted store. Admin/owner role required. */
     remove: {
         params: {
+            /** Integration name the credential belongs to. */
             service: string;
+            /** Env-var name to remove. */
             envVar: string;
         };
         result: {
             removed: boolean;
         };
     };
+    /** Check whether a service's required credentials are present and, if a live probe is declared for it, exercise the service to confirm they actually work. Admin/owner role required. */
     test: {
         params: {
+            /** Integration name to test. */
             service: string;
         };
         result: {
@@ -1186,20 +1522,28 @@ type CredentialsActions = {
             message: string;
         };
     };
+    /** Re-encrypt all stored credentials under the current master key (ALMADAR_CREDENTIAL_MASTER_KEY), retiring ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS. Admin/owner role required. */
     rotate: {
         params: Record<string, never>;
         result: {
+            /** Entries successfully re-encrypted under the current key. */
             rotated: number;
+            /** Entries already under the current key (no-op). */
             alreadyCurrent: number;
+            /** Entries that could not be decrypted with either key (data loss risk). */
             unreadable: number;
         };
     };
 };
 type OtelActions = {
+    /** Start a trace span (in-memory backend — no OpenTelemetry SDK/exporter). */
     startSpan: {
         params: {
+            /** Span name. */
             name: string;
+            /** Key-value attributes attached to the span. */
             attributes?: IntegrationParams;
+            /** Existing trace id to attach this span to; a new one is generated when omitted. */
             traceId?: string;
         };
         result: {
@@ -1207,38 +1551,52 @@ type OtelActions = {
             traceId: string;
         };
     };
+    /** Mark a span ended, optionally recording its final status; no-op (returns ended:false) for an unknown span id. */
     endSpan: {
         params: {
+            /** Span id from startSpan. */
             spanId: string;
+            /** Final span status. */
             status?: 'ok' | 'error';
         };
         result: {
             ended: boolean;
         };
     };
+    /** Attach a timestamped event to an open span; no-op (returns added:false) for an unknown span id. */
     addEvent: {
         params: {
+            /** Span id from startSpan. */
             spanId: string;
+            /** Event name. */
             name: string;
+            /** Key-value attributes attached to the event. */
             attributes?: IntegrationParams;
         };
         result: {
             added: boolean;
         };
     };
+    /** Record a metric sample: counters accumulate, gauges overwrite, histograms append to the sample list. */
     recordMetric: {
         params: {
+            /** Metric name. */
             name: string;
+            /** Sample value. */
             value: number;
+            /** Aggregation kind; defaults to 'counter'. */
             type?: 'counter' | 'gauge' | 'histogram';
+            /** Key-value labels attached to the metric (replaces prior labels on the same name). */
             labels?: IntegrationParams;
         };
         result: {
             recorded: boolean;
         };
     };
+    /** Fetch a stored span's full record by id; null if unknown. */
     getSpan: {
         params: {
+            /** Span id from startSpan. */
             spanId: string;
         };
         result: {
@@ -1251,6 +1609,7 @@ type OtelActions = {
             attributes: IntegrationParams;
         } | null;
     };
+    /** Fetch all recorded metrics, keyed by metric name. */
     getMetrics: {
         params: Record<string, never>;
         result: Record<string, {
@@ -1263,8 +1622,10 @@ type OtelActions = {
     };
 };
 type CLIActions = {
+    /** Validate an orbital schema by writing it to a temp file and shelling out to `npx @almadar/cli validate --format=json`. */
     validate: {
         params: {
+            /** Raw .orb schema content to validate. */
             schema: string;
         };
         result: {
@@ -1276,11 +1637,16 @@ type CLIActions = {
     };
 };
 type DeepAgentActions = {
+    /** Send a chat message to the DeepAgent server (POST /api/agent/message), continuing an existing thread or starting one. */
     sendMessage: {
         params: {
+            /** Message text. */
             message: string;
+            /** Existing thread id to continue; a new thread starts when omitted. */
             threadId?: string;
+            /** Named skill to invoke for this message. */
             skill?: string;
+            /** Extra context passed through to the agent. */
             context?: IntegrationParams;
         };
         result: {
@@ -1288,16 +1654,20 @@ type DeepAgentActions = {
             threadId: string;
         };
     };
+    /** Cancel an in-flight generation on a DeepAgent thread (POST /api/agent/cancel). */
     cancelGeneration: {
         params: {
+            /** Thread whose generation to cancel. */
             threadId: string;
         };
         result: {
             cancelled: boolean;
         };
     };
+    /** Validate a schema via the DeepAgent server (POST /api/schema/validate). */
     validateSchema: {
         params: {
+            /** Schema content to validate. */
             schema: string;
         };
         result: {
@@ -1305,9 +1675,12 @@ type DeepAgentActions = {
             errors: string[];
         };
     };
+    /** Compile a schema to a target shell via the DeepAgent server (POST /api/schema/compile). */
     compileSchema: {
         params: {
+            /** Schema content to compile. */
             schema: string;
+            /** Target codegen shell (e.g. 'typescript'). */
             shell?: string;
         };
         result: {
@@ -1315,8 +1688,10 @@ type DeepAgentActions = {
             files: string[];
         };
     };
+    /** Fetch a thread's message history via the DeepAgent server (POST /api/agent/history). */
     getThreadHistory: {
         params: {
+            /** Thread id. */
             threadId: string;
         };
         result: {
@@ -1329,10 +1704,14 @@ type DeepAgentActions = {
     };
 };
 type DatabaseActions = {
+    /** Run a single read-only SELECT against a Postgres connection (write statements and multi-statement SQL are rejected before execution). */
     query: {
         params: {
+            /** Env-var NAME whose value is the Postgres connection string — never the secret itself; resolved from the credential store/environment at run time. */
             connectionRef: string;
+            /** SQL text; must be exactly one SELECT statement. */
             sql: string;
+            /** Positional bind parameters for the query. */
             params?: DatabaseQueryParamValue[];
         };
         result: {
@@ -1342,8 +1721,10 @@ type DatabaseActions = {
     };
 };
 type WikimediaActions = {
+    /** Look up a Wikipedia page (redirect-resolved): a one-line description, a Commons thumbnail, and the lead-section extract; empty fields on a miss. */
     getPage: {
         params: {
+            /** Page title to look up. */
             title: string;
         };
         result: {
@@ -1355,25 +1736,32 @@ type WikimediaActions = {
     };
 };
 type IconifyActions = {
+    /** Check whether an icon exists at the given Iconify API path (a GET, not a HEAD, despite the name). */
     svgExists: {
         params: {
+            /** Iconify API path segment to probe, e.g. 'prefix/name.svg'. */
             path: string;
         };
         result: {
             exists: boolean;
         };
     };
+    /** Search Iconify's icon sets by relevance. */
     search: {
         params: {
+            /** Search query text. */
             query: string;
+            /** Maximum icon ids to return; defaults to 1. */
             limit?: number;
         };
         result: {
             icons: string[];
         };
     };
+    /** Fetch an icon's raw SVG body (for color-tone classification); null if the icon or its collection isn't found. */
     getIconBody: {
         params: {
+            /** Icon id in "prefix:name" form. */
             iconId: string;
         };
         result: {
@@ -1382,9 +1770,12 @@ type IconifyActions = {
     };
 };
 type ArxivActions = {
+    /** Search arXiv's public Atom API by relevance. */
     search: {
         params: {
+            /** Search query text (matched across all fields). */
             query: string;
+            /** Maximum results to return; defaults to 8. */
             maxResults?: number;
         };
         result: {