deepspace 0.4.2 → 0.4.4

package/dist/server.d.ts

@@ -1,6 +1,7 @@
-import { LanguageModel, ModelMessage } from 'ai';
+import { LanguageModel, ToolSet, ModelMessage } from 'ai';
 import * as Y from 'yjs';
 import * as better_auth from 'better-auth';
+import { betterAuth } from 'better-auth';
 import * as better_auth_plugins from 'better-auth/plugins';
 import { Context } from 'hono';
 
@@ -31,6 +32,30 @@ type ToolResult = {
     success: false;
     error: string;
 };
+/**
+ * Page size the assistant defaults to for `records.query` when it omits
+ * `limit`. Keeps a model-issued unbounded scan from blowing the tool-result
+ * byte cap and gives the model a usable first page. Raise `limit` to page
+ * through more (still subject to the cap; see
+ * `DEFAULT_CONTEXT_CONFIG.toolResultCap` / `capToolResultSize`, which truncates
+ * oversized pages gracefully rather than dropping them).
+ *
+ * Applied by the AI tool layer via `applyAiToolDefaults`, never by the shared
+ * tools-api dispatch, so internal record readers (chat history, cron, app
+ * `actions.query`) stay unbounded.
+ */
+declare const DEFAULT_QUERY_LIMIT = 50;
+/**
+ * Fill in assistant-only parameter defaults for a built-in tool call.
+ *
+ * Applied by the AI tool layer (`buildTools`) before a model-issued tool call
+ * is dispatched, so the default only affects calls the assistant makes.
+ * `records.query` doubles as the SDK's general record-read primitive (chat
+ * history, cron, app `actions.query`); those callers reach the tools dispatch
+ * directly and must return every row, so this default must not live in the
+ * dispatch itself. Pure and non-mutating.
+ */
+declare function applyAiToolDefaults(toolName: string, params: Record<string, unknown>): Record<string, unknown>;
 /**
  * Built-in tool definitions for storage, record, schema, user, and backup operations
  */
@@ -470,7 +495,7 @@ interface CronContext {
     };
     /**
      * Call a platform integration endpoint (e.g. "openai/chat-completion",
-     * "freepik/text-to-image-classic"). Billed to the app owner — the same
+     * "fal/run-model"). Billed to the app owner using the same
      * APP_OWNER_JWT the rest of the SDK uses for server-side billed calls.
      */
     integrations: {
@@ -569,6 +594,49 @@ interface DeepSpaceAIOptions {
  */
 declare function createDeepSpaceAI(env: DeepSpaceAIEnv, provider: Provider, options?: DeepSpaceAIOptions): DeepSpaceModelFactory;
 
+/**
+ * Composio tools for the Vercel AI SDK.
+ *
+ * Turns the platform's Composio integration into ready-to-use Vercel AI SDK
+ * tools, so an agent (or the DeepSpace AI chat) can take actions on a user's
+ * connected apps. Each returned tool's `execute()` calls our own
+ * `composio/execute-tool` endpoint through the api-worker proxy, so our auth
+ * and per-user billing apply. This is the managed-proxy equivalent of
+ * Composio's `@composio/vercel` provider, which talks straight to Composio.
+ *
+ * `authToken` must be the END USER's JWT: Composio resolves the user's
+ * connected accounts by the JWT subject, and that user is billed.
+ *
+ * Usage (inside a request handler, e.g. /api/ai/chat):
+ *
+ *   import { composioTools, createDeepSpaceAI } from 'deepspace/worker'
+ *   const jwt = c.req.header('Authorization')!.slice(7)
+ *   const tools = await composioTools(c.env, { toolkit: 'gmail', authToken: jwt })
+ *   const ai = createDeepSpaceAI(c.env, 'anthropic', { authToken: jwt })
+ *   const result = streamText({ model: ai('claude-sonnet-4-6'), prompt, tools })
+ *
+ * Merge with your own tools: `tools: { ...buildTools(executor), ...composio }`.
+ */
+
+interface ComposioToolsOptions {
+    /** End user's JWT. Required: the tools run as this user and bill them. */
+    authToken: string;
+    /** Restrict to one toolkit (e.g. 'gmail', 'github'). */
+    toolkit?: string;
+    /** Explicit tool slugs to expose (e.g. ['GMAIL_SEND_EMAIL']). */
+    tools?: string[];
+    /** Natural-language search to pick relevant tools. */
+    search?: string;
+    /** Cap how many tools are exposed (default 20). Keep small: the LLM sees them all. */
+    limit?: number;
+}
+/**
+ * Fetch Composio tools for the given scope and return them as a Vercel AI SDK
+ * `ToolSet`. One `list-tools` call provides each tool's JSON Schema; each tool
+ * executes via `composio/execute-tool` as the authenticated user.
+ */
+declare function composioTools(env: ApiWorkerEnv, options: ComposioToolsOptions): Promise<ToolSet>;
+
 /**
  * captureScreenshot — call platform-worker /internal/screenshot.
  *
@@ -657,8 +725,17 @@ declare function truncateOldToolResults(messages: ChatTurn[], keepRecent: number
  */
 declare function applySlidingWindow(messages: ChatTurn[], charCap: number, minKept: number): ChatTurn[];
 /**
- * Replace oversized tool results with an error telling the agent to narrow
- * its query. Keeps a small preview so the agent can see what it got.
+ * Keep an individual tool result under `byteCap`.
+ *
+ * If the payload carries a list of items (e.g. a `records.query` result), it is
+ * degraded gracefully: as many leading items as fit under the cap are returned,
+ * the `success: true` shape is preserved, and `{ truncated, returned, total }`
+ * flags are merged in next to the array so callers can still use the partial
+ * data and paginate for the rest.
+ *
+ * Only when there is no array to trim (or even an empty list still overflows
+ * because of oversized sibling fields) does it fall back to replacing the
+ * result with an error + small preview telling the agent to narrow its query.
  */
 declare function capToolResultSize(result: unknown, byteCap: number): unknown;
 /**
@@ -2019,6 +2096,49 @@ declare abstract class CronRoom<E = Record<string, unknown>> extends BaseRoom<E>
     protected abstract onTask(taskName: string): void | Promise<void>;
 }
 
+interface SecretMetadata {
+    name: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+declare class SecretsRoom<E extends {
+    APP_SECRETS_KEY?: string;
+} = {
+    APP_SECRETS_KEY?: string;
+}> extends BaseRoom<E> {
+    private initialized;
+    protected onMessage(_ws: WebSocket, _user: UserAttachment, _message: {
+        type: string;
+    }): void;
+    fetch(request: Request): Promise<Response>;
+    protected onRequest(request: Request): Promise<Response>;
+    list(): Promise<SecretMetadata[]>;
+    pull(): Promise<Record<string, string>>;
+    patch(body: {
+        set?: Record<string, string>;
+        delete?: string[];
+        updatedBy?: string;
+    }): Promise<{
+        version: number;
+        secrets: SecretMetadata[];
+    }>;
+    replace(body: {
+        secrets?: Record<string, string>;
+        updatedBy?: string;
+    }): Promise<{
+        version: number;
+        secrets: SecretMetadata[];
+    }>;
+    private transaction;
+    private migrateLegacyProductionSecrets;
+    private ensureInitialized;
+    private requireKey;
+    private storeVersion;
+    private bumpStoreVersion;
+}
+
 /**
  * JobRoom — Per-app durable background-job execution Durable Object.
  *
@@ -2320,7 +2440,7 @@ declare const ALLOWED_BINDING_TYPES: Set<string>;
  *
  * Includes:
  *   - Static-asset + service bindings the platform sets up automatically.
- *   - SDK-managed env (auth, identity, owner JWT).
+ *   - SDK-managed env (auth, identity, owner JWT, app-secret encryption root).
  *   - The auto-attached cost-tracking AE dataset (`USAGE_EVENTS`).
  *
  * DO binding names (RECORD_ROOMS, YJS_ROOMS, etc.) are NOT in this set
@@ -2971,11 +3091,6 @@ declare function timingSafeEqualHex(a: string, b: string): Promise<boolean>;
 
 declare function decodeJwtPayload(token: string | null | undefined): TokenDebugInfo | undefined;
 
-/**
- * Better Auth configuration factory for DeepSpace
- *
- * Provides pre-configured Better Auth instances for Cloudflare Workers + D1.
- */
 interface DeepSpaceAuthConfig {
     /** D1 database binding */
     database: D1Database;
@@ -2993,29 +3108,28 @@ interface DeepSpaceAuthConfig {
         clientId: string;
         clientSecret: string;
     };
+    /** Microsoft (Entra ID) OAuth credentials (optional) */
+    microsoft?: {
+        clientId: string;
+        clientSecret: string;
+    };
+    /**
+     * Apple (Sign in with Apple) credentials (optional). Pass the raw
+     * Sign-in-with-Apple key material; the ES256 client-secret JWT is minted
+     * on demand, so there is no six-month token to rotate by hand.
+     */
+    apple?: {
+        clientId: string;
+        teamId: string;
+        keyId: string;
+        privateKey: string;
+    };
     /** Enable email/password authentication */
     emailAndPassword?: boolean;
     /** Trusted origins for CORS */
     trustedOrigins?: string[];
 }
-/**
- * Create a Better Auth instance configured for DeepSpace.
- *
- * This is called per-request in the auth worker since D1 bindings
- * are request-scoped in Cloudflare Workers.
- */
 declare function createDeepSpaceAuth(config: DeepSpaceAuthConfig): better_auth.Auth<{
-    database: D1Database;
-    baseURL: string;
-    secret: string;
-    emailAndPassword: {
-        enabled: boolean;
-    };
-    socialProviders: Record<string, {
-        clientId: string;
-        clientSecret: string;
-    }>;
-    trustedOrigins: string[];
     plugins: [{
         id: "organization";
         endpoints: better_auth_plugins.OrganizationEndpoints<better_auth_plugins.OrganizationOptions & {
@@ -3815,9 +3929,74 @@ declare function createDeepSpaceAuth(config: DeepSpaceAuthConfig): better_auth.A
             INVALID_TWO_FACTOR_COOKIE: better_auth.RawError<"INVALID_TWO_FACTOR_COOKIE">;
         };
     }];
+    advanced?: {
+        cookies: {
+            state: {
+                attributes: {
+                    sameSite: "none";
+                    secure: true;
+                };
+            };
+            oauth_state: {
+                attributes: {
+                    sameSite: "none";
+                    secure: true;
+                };
+            };
+        };
+    } | undefined;
+    database: D1Database;
+    baseURL: string;
+    secret: string;
+    emailAndPassword: {
+        enabled: boolean;
+    };
+    socialProviders: Parameters<typeof betterAuth>[0]["socialProviders"];
+    trustedOrigins: string[];
 }>;
 type DeepSpaceAuth = ReturnType<typeof createDeepSpaceAuth>;
 
+interface SecretsEnv {
+    SECRETS_ROOMS?: DurableObjectNamespace;
+    APP_SECRETS_KEY?: string;
+    APP_SECRETS_LOCAL_FALLBACK?: string;
+}
+interface SecretRefreshResult {
+    changed: boolean;
+    version: number;
+}
+interface WithFreshSecretsContext {
+    secrets: SecretsClient;
+    attempt: number;
+    refreshed: boolean;
+}
+interface WithFreshSecretsOptions {
+    /**
+     * By default the operation retries only when a forced refresh observes a
+     * changed secret version after an auth-like failure. Set this for idempotent
+     * operations that should retry after a successful refresh even when the
+     * version is unchanged.
+     */
+    retryWhenUnchanged?: boolean;
+}
+interface SecretsClient {
+    get(name: string): Promise<string | undefined>;
+    require(name: string): Promise<string>;
+    getMany(names: string[]): Promise<Record<string, string | undefined>>;
+    preload(names: string[]): Promise<void>;
+    refresh(options?: {
+        force?: boolean;
+    }): Promise<SecretRefreshResult>;
+    checkForUpdates(): Promise<SecretRefreshResult>;
+    invalidate(): void;
+    withFreshSecrets<T>(operation: (ctx: WithFreshSecretsContext) => Promise<T>, options?: WithFreshSecretsOptions): Promise<T>;
+}
+interface CreateSecretsOptions {
+    refreshIntervalMs?: number;
+    now?: () => number;
+}
+declare function createSecrets(env: SecretsEnv, options?: CreateSecretsOptions): SecretsClient;
+
 /**
  * Subscription primitives shared between client (useSubscription hook) and
  * server (requireSubscription helper). Pulled into a shared module so the
@@ -3971,4 +4150,4 @@ declare class RefundError extends Error {
     constructor(message: string, status: number);
 }
 
-export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CancelSubscriptionError, type CancelSubscriptionOpts, type CancelSubscriptionResult, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DebugApiContext, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlanInfo, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, type RecordContext, RecordRoom, type RecordRoomConfig, RefundError, type RefundOpts, type RefundResult, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTION_SCHEMAS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type SharedConnection, type StoredRecord, SubscriptionAuthError, type SubscriptionContext, type SubscriptionRead, SubscriptionRequiredError, type SubscriptionStatus, type Summarizer, type TokenDebugInfo, type ToolResult, type ToolSchema, type ToolsApiContext, USERS_COLUMNS, type User, type UserAttachment, type UserContext, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, type YjsContext, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, broadcastChange, broadcastYjsUpdate, buildCronContext, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, cancelSubscription, capToolResultSize, captureScreenshot, checkFieldPermissions, coerceValue, collectionTableName, columnId, computeDoMigration, computeHmacHex, createChat, createDeepSpaceAI, createDeepSpaceAuth, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, deleteRecord, enqueueJob, executeQuery, getAllUsers, getChat, getGlobalDOSchemas, getGlobalDOType, getOrCreateYjsDoc, getRecord, getRolePermissions, getSubscription, getUser, getYjsDocKey, handleApiRequest, handleDelete, handlePut, handleSetRole, handleSubscribe, handleToolsRequest, handleUnsubscribe, handleUserList, handleUserUpdate, handleYjsBinaryMessage, handleYjsJoin, handleYjsLeave, isAutoProvision, isOwner, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, putRecord, readRecord, recordMatchesSubscription, refundInvoice, registerUser, requireSubscription, resolveAppName, resolveColumn, rowToData, runMigrations, saveYjsDoc, timingSafeEqualHex, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema };
+export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CancelSubscriptionError, type CancelSubscriptionOpts, type CancelSubscriptionResult, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ComposioToolsOptions, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CreateSecretsOptions, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_QUERY_LIMIT, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DebugApiContext, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlanInfo, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, type RecordContext, RecordRoom, type RecordRoomConfig, RefundError, type RefundOpts, type RefundResult, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTION_SCHEMAS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type SecretMetadata, type SecretRefreshResult, type SecretsClient, type SecretsEnv, SecretsRoom, type SharedConnection, type StoredRecord, SubscriptionAuthError, type SubscriptionContext, type SubscriptionRead, SubscriptionRequiredError, type SubscriptionStatus, type Summarizer, type TokenDebugInfo, type ToolResult, type ToolSchema, type ToolsApiContext, USERS_COLUMNS, type User, type UserAttachment, type UserContext, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, type WithFreshSecretsContext, type WithFreshSecretsOptions, type YjsContext, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applyAiToolDefaults, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, broadcastChange, broadcastYjsUpdate, buildCronContext, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, cancelSubscription, capToolResultSize, captureScreenshot, checkFieldPermissions, coerceValue, collectionTableName, columnId, composioTools, computeDoMigration, computeHmacHex, createChat, createDeepSpaceAI, createDeepSpaceAuth, createScopedR2Handler, createSecrets, dataToColumnValues, decodeJwtPayload, deleteChatCascade, deleteRecord, enqueueJob, executeQuery, getAllUsers, getChat, getGlobalDOSchemas, getGlobalDOType, getOrCreateYjsDoc, getRecord, getRolePermissions, getSubscription, getUser, getYjsDocKey, handleApiRequest, handleDelete, handlePut, handleSetRole, handleSubscribe, handleToolsRequest, handleUnsubscribe, handleUserList, handleUserUpdate, handleYjsBinaryMessage, handleYjsJoin, handleYjsLeave, isAutoProvision, isOwner, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, putRecord, readRecord, recordMatchesSubscription, refundInvoice, registerUser, requireSubscription, resolveAppName, resolveColumn, rowToData, runMigrations, saveYjsDoc, timingSafeEqualHex, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema };