@mastra/mcp-docs-server 1.2.19-alpha.0 → 1.2.19-alpha.14

package/.docs/docs/sandbox/filesystem.md

@@ -7,7 +7,7 @@ A filesystem gives an agent tools for reading, writing, listing, and [searching]
 Configure files in two ways:
 
 - [Direct filesystem access](#direct-filesystem-access) uses `filesystem` with one filesystem provider or a [`CompositeFilesystem`](#manual-composition) that you create yourself.
-- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When the workspace also has a static sandbox, Mastra attempts to mount each provider at its configured path inside the sandbox so commands can access the same files. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
+- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When a static sandbox and filesystem provider support mounting, Mastra automatically mounts the provider at its configured path. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
 
 Configure either `filesystem` or `mounts`, not both. Configuring both throws a `WorkspaceError` with the code `INVALID_CONFIG`.
 
@@ -71,7 +71,7 @@ See [Search](https://mastra.ai/docs/sandbox/search) to index the files for keywo
 
 ## Mounts
 
-Use `mounts` when programs inside a sandbox need to access persistent files by path. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
+Use `mounts` when programs inside a sandbox need to access persistent files by path. Mastra creates the mount automatically when the sandbox and filesystem provider support it. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
 
 For example, mount an S3 bucket at `/workspace` inside a Daytona sandbox:
 
@@ -180,7 +180,7 @@ Use manual composition when another part of your application needs the composite
 
 ## Mount availability
 
-File tools and composite routing work without FUSE. Remote sandboxes can use FUSE to make cloud storage visible to commands. `LocalSandbox` uses symlinks instead.
+File tools and composite routing work without a sandbox mount. When a remote sandbox and filesystem provider support mounting, `mounts` automatically uses FUSE to make the files visible to commands. `LocalSandbox` uses symlinks instead.
 
 Built-in sandbox mounting currently includes:
 
@@ -195,27 +195,27 @@ Remote mounts may require `s3fs`, `gcsfuse`, or `blobfuse2` inside the sandbox.
 
 If a sandbox mount is unavailable or fails, the workspace remains usable. File tools continue to access the provider through its SDK, but commands can't see that path. Mastra describes these providers to the agent as available through file tools only.
 
-## Multi-tenant filesystems
+## Filesystems per user or thread
 
 The `filesystem` option accepts a resolver when storage should vary by request, user, role, or tenant:
 
 ```typescript
 const workspace = new Workspace({
   filesystem: ({ requestContext }) => {
-    const tenantId = requestContext.get('tenant-id') as string
+    const userId = requestContext.get('user-id') as string
 
     return new S3Filesystem({
       bucket: process.env.S3_BUCKET!,
       region: process.env.S3_REGION!,
-      prefix: `tenants/${tenantId}`,
+      prefix: `users/${userId}`,
     })
   },
 })
 ```
 
-Each tenant gets its own filesystem view, and file tools resolve the provider from the request context automatically.
+Each user gets a separate filesystem view, and file tools resolve the provider from the request context automatically.
 
-`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/sandbox/overview).
+`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Sandboxes per user or thread](https://mastra.ai/docs/sandbox/overview).
 
 ## Policies and containment
 

package/.docs/docs/sandbox/overview.md

@@ -2,27 +2,27 @@
 
 # Sandboxes and filesystems
 
-A sandbox gives your agent an environment where it can run commands, execute code, install dependencies, and manage processes. Sandboxes can isolate potentially risky agent-run code from your host, and they can also provide a place to run longer-lived or more resource-intensive work outside your application process.
+A sandbox gives your agent an isolated environment where it can run commands, execute code, install dependencies, and manage processes. This lets agents perform work that would be risky, resource-intensive, or impractical to run directly inside your application.
 
-[Filesystems](https://mastra.ai/docs/sandbox/filesystem) give the agent files it can read, write, and [search](https://mastra.ai/docs/sandbox/search). They can provide a knowledge base for your agent, or be shared with a sandbox so commands can work with the same files and keep data beyond the sandbox's lifetime.
+Sandboxes are often temporary, so files created inside them may disappear when the environment stops. A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives the agent a place to read, write, and [search](https://mastra.ai/docs/sandbox/search) files that can outlive the sandbox. You can use one to keep outputs between runs, seed a new sandbox with existing files, or give the agent documents it can search while working. Filesystems also work without a sandbox, for example when an agent only needs a knowledge base or access to files in a service such as Google Drive.
 
 ## When to use sandboxes
 
-Sandboxes work well for:
+Use a sandbox when an agent needs to:
 
-- **Coding agents and software factories**: Clone repositories and run shell, Git, build, or test workflows without giving autonomous agents access to the host system.
-- **Deep research and analysis**: Use specialized libraries to process downloaded PDFs or presentations and produce new artifacts.
-- **Long-running and parallel tasks**: Run work in separate environments without tying it to one request or sharing files and processes.
+- Clone repositories and run shell, Git, build, or test workflows in a separate environment.
+- Process PDFs, presentations, or other files with specialized libraries and produce new artifacts.
+- Run long-lived or parallel work in separate environments with isolated files and processes.
 
 If an agent only needs to read, write, or search files, configure [direct filesystem access](https://mastra.ai/docs/sandbox/filesystem).
 
 ## Quickstart
 
-Give an agent a local sandbox and filesystem:
+Give an agent a local sandbox:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
+import { LocalSandbox, Workspace } from '@mastra/core/workspace'
 
 export const codingAgent = new Agent({
   id: 'coding-agent',
@@ -33,20 +33,15 @@ export const codingAgent = new Agent({
     sandbox: new LocalSandbox({
       workingDirectory: './workspace',
     }),
-    filesystem: new LocalFilesystem({
-      basePath: './workspace',
-    }),
   }),
 })
 
 await codingAgent.generate('List the files in the sandbox directory')
 ```
 
-> **Warning:** `LocalSandbox` is the quickest sandbox to set up, but commands run on the host by default. Enable [native isolation](#localsandbox) whenever possible. For applications exposed to untrusted users, use a remote or container backend with a stronger isolation boundary instead.
-
-To use a different sandbox for each user, tenant, or thread, configure a [sandbox resolver](#multi-tenant-sandboxes) instead.
+> **Warning:** `LocalSandbox` runs commands on the application host by default and isn't isolated or secure. Enable [native isolation](#localsandbox), or use a remote or container sandbox when running untrusted code.
 
-The `LocalSandbox` above is one static instance. Every request and memory thread that uses `codingAgent` shares its files, processes, and lifecycle state. A memory thread doesn't create an isolated sandbox by itself.
+A static sandbox is shared across every request and memory thread that uses the agent. Use a [resolver](#sandboxes-per-user-or-thread) when each user or thread needs a separate environment. See [Lifecycle and persistence](#lifecycle-and-persistence) for sharing and cleanup details.
 
 ## Using the sandbox
 
@@ -74,7 +69,7 @@ const workspace = new Workspace({
 })
 ```
 
-Omitting a tool entry keeps its capability-driven default. Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
+Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
 
 See the [sandbox tools reference](https://mastra.ai/reference/workspace/workspace-class) for all generated tools and the [tool configuration reference](https://mastra.ai/reference/workspace/workspace-class) for approvals, output limits, and hooks.
 
@@ -109,17 +104,12 @@ export const startServerTool = createTool({
 })
 ```
 
-## Supported backends
+## Sandboxes
 
 ### `LocalSandbox`
 
 [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) executes commands on the same machine as your Mastra application. By default, commands run directly on the host with the permissions of the application process.
 
-Enable native isolation to restrict filesystem and network access at the operating-system level:
-
-- **macOS**: Seatbelt (`sandbox-exec`)
-- **Linux**: Bubblewrap (`bwrap`)
-
 ```typescript
 const sandbox = new LocalSandbox({
   workingDirectory: './workspace',
@@ -131,11 +121,13 @@ const sandbox = new LocalSandbox({
 })
 ```
 
-Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system. The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
+Enable native isolation to restrict filesystem and network access at the operating-system level. On macOS, native isolation uses Seatbelt (`sandbox-exec`). On Linux, it uses Bubblewrap (`bwrap`). Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system.
 
-### Other backends
+The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
 
-Use a remote or container backend when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each backend has its own isolation, persistence, networking, and mount behavior:
+### Remote sandboxes
+
+Use a remote or container sandbox when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each sandbox has its own isolation, persistence, networking, and mount behavior:
 
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
@@ -149,47 +141,40 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)
 - [Vercel](https://mastra.ai/integrations/sandboxes/vercel)
 
-If Mastra doesn't support your execution backend, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
+If Mastra doesn't support your sandbox provider, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
 
 ## Filesystem
 
-Each sandbox has a native filesystem that commands can use. Treat it as ephemeral because its contents follow the sandbox's lifecycle.
+Every sandbox has a filesystem for commands. `LocalSandbox` uses the host filesystem, while remote sandboxes have isolated filesystems that are often temporary. For files that need to outlive a sandbox, use external storage.
+
+Mastra filesystems connect agents and sandboxes to provider-backed storage such as Amazon S3, Google Cloud Storage, or Google Drive. Configuring one gives the agent tools to read, write, and search files. When a remote sandbox and provider support mounting, Mastra automatically mounts the storage through Filesystem in Userspace (FUSE). Commands use normal file paths while the provider stores changes outside the sandbox.
 
-To seed a sandbox with files or keep files between runs, give the agent a [filesystem](https://mastra.ai/docs/sandbox/filesystem). Use mounts when sandbox commands need access to the same files.
+See [Filesystem](https://mastra.ai/docs/sandbox/filesystem) for providers, file tools, and mounts.
 
-## Multi-tenant sandboxes
+## Sandboxes per user or thread
 
 Use a **resolver** when each user, tenant, or thread needs a separate sandbox. Set `sandboxCacheKey` to the identity that owns the sandbox so later requests reuse the same live environment.
 
 This example creates and caches one Daytona sandbox per user:
 
 ```typescript
-import type { RequestContext } from '@mastra/core/request-context'
 import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 
-const getUserId = (requestContext: RequestContext) => {
-  const userId = requestContext.get('user-id')
-  if (typeof userId !== 'string' || !userId) {
-    throw new Error('A user ID is required to resolve this sandbox')
-  }
-
-  return userId
-}
-
 const workspace = new Workspace({
   sandbox: async ({ requestContext }) => {
-    const sandbox = new DaytonaSandbox({ id: `user-${getUserId(requestContext)}` })
+    const userId = requestContext.get('user-id') as string
+    const sandbox = new DaytonaSandbox({ id: `user-${userId}` })
     await sandbox.start()
     return sandbox
   },
-  sandboxCacheKey: ({ requestContext }) => getUserId(requestContext),
+  sandboxCacheKey: ({ requestContext }) => requestContext.get('user-id') as string,
 })
 ```
 
 The first request from a user creates the sandbox. Later requests with the same user ID reuse it.
 
-For a sandbox with persistent storage, create the filesystem and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
+For a sandbox with persistent storage, create a [filesystem](https://mastra.ai/docs/sandbox/filesystem) and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
 
 ```typescript
 import { MASTRA_THREAD_ID_KEY, type RequestContext } from '@mastra/core/request-context'
@@ -197,14 +182,8 @@ import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 import { S3Filesystem } from '@mastra/s3'
 
-const getThreadId = (requestContext: RequestContext) => {
-  const threadId = requestContext.get(MASTRA_THREAD_ID_KEY)
-  if (typeof threadId !== 'string' || !threadId) {
-    throw new Error('A memory thread is required to resolve this sandbox')
-  }
-
-  return threadId
-}
+const getThreadId = (requestContext: RequestContext) =>
+  requestContext.get(MASTRA_THREAD_ID_KEY) as string
 
 const createThreadFilesystem = (threadId: string) =>
   new S3Filesystem({
@@ -234,25 +213,13 @@ The first request in a thread runs the resolver and starts the sandbox. Later re
 
 The example mounts the filesystem inside the resolver because static `mounts` can't be combined with a sandbox resolver. Generated tools resolve the filesystem and sandbox from the request context automatically.
 
-### Resolver ownership
-
-You are responsible for every sandbox returned by a resolver. It must be ready to use when returned. Keep track of it and destroy it through your application lifecycle code when it's no longer needed. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
-
-Resolvers are incompatible with `mounts` and [`lsp: true`](https://mastra.ai/docs/sandbox/lsp), because both require a static sandbox during configuration. Using a resolver with `mounts` throws an `INVALID_CONFIG` error. With `lsp: true`, Mastra disables LSP and logs a warning.
+> **Warning:** Your application owns sandboxes returned by a resolver. Destroy them and call `workspace.clearSandboxCache(cacheKey)` when the user, thread, or session ends. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
 
 ### Tool availability
 
-With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it:
-
-```typescript
-const processManager = workspace.sandbox?.processes
-
-if (processManager) {
-  await processManager.spawn('pnpm dev')
-}
-```
+With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it.
 
-With a [resolver-backed sandbox](#multi-tenant-sandboxes), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
+With a [resolver-backed sandbox](#sandboxes-per-user-or-thread), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 
@@ -292,7 +259,7 @@ Who shares a sandbox depends on where you configure it and whether you use a res
 | Resource-scoped resolver   | The resolver caches one sandbox for each resource ID.                                                                               |
 | Thread-scoped resolver     | A memory thread keeps its sandbox across requests in that thread.                                                                   |
 
-A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Multi-tenant sandboxes](#multi-tenant-sandboxes).
+A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Sandboxes per user or thread](#sandboxes-per-user-or-thread).
 
 ### Start
 

package/.docs/docs/server/middleware.md

@@ -6,6 +6,10 @@ Mastra servers can execute custom middleware functions before or after an API ro
 
 A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next` function. If it returns a `Response` the request is short-circuited. Calling `next()` continues processing the next middleware or route handler.
 
+> **Note:** Middleware handlers use Hono's signature, so they run on Hono-based serving paths: `mastra dev` and `mastra build`, the [Hono adapter](https://mastra.ai/reference/server/hono-adapter), and adapters built on it such as `@mastra/next` and `@mastra/tanstack-start`. Adapters for other frameworks (Express, Fastify, Koa) can't run Hono handlers and log a warning at startup when middleware is configured. Register middleware through the framework's own API there instead.
+>
+> User middleware never runs on routes declared public with `requiresAuth: false`, so it can't block endpoints the framework needs to keep reachable, such as the Studio sign-in routes.
+
 ```typescript
 import { Mastra } from '@mastra/core'
 

package/.docs/docs/server/server-adapters.md

@@ -424,11 +424,12 @@ See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) docu
 
 ## Initialization flow
 
-Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
+Calling `init()` runs four steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
 
 1. `registerContextMiddleware()`: Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
 2. `registerAuthMiddleware()`: Runs the adapter auth hook during initialization. Official adapters enforce auth inline when Mastra registers built-in routes and `registerApiRoute()` routes, so raw framework routes should use the adapter's exported `createAuthMiddleware()` helper when they need Mastra auth.
-3. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
+3. `registerUserMiddleware()`: Registers [middleware](https://mastra.ai/docs/server/middleware) from the `server.middleware` config and `mastra.setServerMiddleware()`. Middleware handlers use Hono's signature, so Hono-based adapters (`@mastra/hono` and the adapters built on it) mount them; other adapters log a warning instead of silently ignoring the config.
+4. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
 
 ### Manual initialization
 
@@ -445,6 +446,9 @@ server.registerContextMiddleware();
 // Middleware that needs Mastra context
 app.use(customMiddleware);
 
+// Registers `server.middleware` and `setServerMiddleware()` middleware
+server.registerUserMiddleware();
+
 await server.registerRoutes();
 
 // Routes after Mastra
@@ -566,11 +570,12 @@ When using server adapters, configuration comes from two places: the Mastra `ser
 
 The adapter reads these settings from `mastra.getServer()`:
 
-| Option          | Description                                                                                                                                     |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth`          | Authentication config, used by `registerAuthMiddleware()`.                                                                                      |
-| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`.                                                         |
-| `onError`       | Custom error handler called when an unhandled error occurs in a route handler. See [server.onError](https://mastra.ai/reference/configuration). |
+| Option          | Description                                                                                                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth`          | Authentication config, used by `registerAuthMiddleware()`.                                                                                                                                                        |
+| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`.                                                                                                                           |
+| `onError`       | Custom error handler called when an unhandled error occurs in a route handler. See [server.onError](https://mastra.ai/reference/configuration).                                                                   |
+| `middleware`    | User [middleware](https://mastra.ai/docs/server/middleware), registered by `registerUserMiddleware()`. Hono-based adapters run it; Express, Fastify, and Koa log a warning because Hono handlers can't run there. |
 
 ### Adapter constructor only
 
@@ -595,7 +600,6 @@ These `server` config options are only used by `mastra build` and have no effect
 | `cors`         | `mastra build` adds CORS middleware     |
 | `timeout`      | `mastra build`                          |
 | `apiRoutes`    | `registerApiRoute()` for `mastra build` |
-| `middleware`   | Middleware config for `mastra build`    |
 
 When using adapters, configure these features directly with your framework. For example, add CORS middleware using Hono's or Express's built-in CORS packages, and set the port when calling your framework's listen function.
 

package/.docs/docs/storage.md

@@ -197,6 +197,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [Convex](https://mastra.ai/integrations/databases/convex)
 - [DuckDB](https://mastra.ai/integrations/databases/duckdb)
 - [DynamoDB](https://mastra.ai/integrations/databases/dynamodb)
+- [Elasticsearch](https://mastra.ai/integrations/databases/elasticsearch)
 - [Google Cloud Spanner](https://mastra.ai/integrations/databases/spanner)
 - [LanceDB](https://mastra.ai/integrations/databases/lancedb)
 - [libSQL](https://mastra.ai/integrations/databases/libsql)
@@ -207,6 +208,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [OracleDB](https://mastra.ai/integrations/databases/oracledb)
 - [PostgreSQL](https://mastra.ai/integrations/databases/postgresql)
 - [Redis](https://mastra.ai/integrations/databases/redis)
+- [Valkey](https://mastra.ai/integrations/databases/valkey)
 - [Upstash](https://mastra.ai/integrations/databases/upstash)
 
 ## Next steps

package/.docs/integrations/channels/imessage.md

@@ -2,10 +2,19 @@
 
 # iMessage
 
-iMessage channels let a Mastra agent receive direct messages and group messages from iMessage. Mastra handles the agent wiring, the webhook route, and the gateway listener; the Photon iMessage adapter docs cover number provisioning, credentials, and webhook registration.
+iMessage channels let a Mastra agent receive direct messages and group messages from iMessage. Two vendor-maintained adapters connect Mastra to iMessage: [Photon](https://app.photon.codes) and [Linq](https://linqapp.com). Mastra handles the agent wiring and the webhook route; the adapter docs cover number provisioning, credentials, and webhook registration.
+
+## Choose an adapter
+
+Both adapters follow the same Mastra wiring, so pick the provider first:
+
+- **Photon**: Hosted or self-hosted iMessage service. Supports webhooks and a [gateway listener](#gateway-listener) that streams messages over an open connection.
+- **Linq**: Hosted iMessage, RCS, and SMS API. Webhook-driven, with tapback reactions and media mapped in both directions.
 
 ## Install the adapter
 
+**Photon**:
+
 Install the Photon iMessage adapter:
 
 **npm**:
@@ -32,9 +41,87 @@ yarn add @photon-ai/chat-adapter-imessage
 bun add @photon-ai/chat-adapter-imessage
 ```
 
+**Linq**:
+
+```bash
+npm install @photon-ai/chat-adapter-imessage
+```
+
+**Tab 3**:
+
+```bash
+pnpm add @photon-ai/chat-adapter-imessage
+```
+
+**Tab 4**:
+
+```bash
+yarn add @photon-ai/chat-adapter-imessage
+```
+
+**Tab 5**:
+
+```bash
+bun add @photon-ai/chat-adapter-imessage
+```
+
+**Tab 6**:
+
+Install the Linq Chat SDK adapter:
+
+**npm**:
+
+```bash
+npm install @linqapp/chat-sdk-adapter
+```
+
+**pnpm**:
+
+```bash
+pnpm add @linqapp/chat-sdk-adapter
+```
+
+**Yarn**:
+
+```bash
+yarn add @linqapp/chat-sdk-adapter
+```
+
+**Bun**:
+
+```bash
+bun add @linqapp/chat-sdk-adapter
+```
+
+**Tab 7**:
+
+```bash
+npm install @linqapp/chat-sdk-adapter
+```
+
+**Tab 8**:
+
+```bash
+pnpm add @linqapp/chat-sdk-adapter
+```
+
+**Tab 9**:
+
+```bash
+yarn add @linqapp/chat-sdk-adapter
+```
+
+**Tab 10**:
+
+```bash
+bun add @linqapp/chat-sdk-adapter
+```
+
 ## Agent configuration
 
-Add `createiMessageAdapter()` to the agent's `channels.adapters` object:
+Add the adapter factory to the agent's `channels.adapters` object:
+
+**Photon**:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -57,6 +144,35 @@ export const imessageAgent = new Agent({
 })
 ```
 
+`threadContext: { maxMessages: 0 }` skips the platform history lookup Mastra runs when an agent is first mentioned in a group chat, which the Photon adapter can't perform.
+
+**Linq**:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createLinqAdapter } from '@linqapp/chat-sdk-adapter'
+
+export const imessageAgent = new Agent({
+  id: 'imessage-agent',
+  name: 'iMessage Agent',
+  instructions: 'Answer questions and help with tasks over iMessage.',
+  model: 'openai/gpt-5.6-sol',
+  channels: {
+    adapters: {
+      imessage: {
+        adapter: createLinqAdapter({
+          apiKey: process.env.LINQ_API_KEY!,
+          signingSecret: process.env.LINQ_WEBHOOK_SECRET!,
+        }),
+        toolDisplay: 'text',
+      },
+    },
+  },
+})
+```
+
+`createLinqAdapter()` takes the credentials directly: `apiKey` is your Linq API key and `signingSecret` comes from the [webhook subscription](#webhook-url). The Linq adapter can fetch thread history, so the default `threadContext` behavior works.
+
 Register the agent on the Mastra instance:
 
 ```typescript
@@ -70,10 +186,14 @@ export const mastra = new Mastra({
 
 Use `imessage` as the adapter key. Mastra derives the webhook path and the `platform` value on `requestContext` from this key.
 
-`toolDisplay: 'text'` describes tool calls in the message, since iMessage has no interactive cards for Approve and Deny actions. `threadContext: { maxMessages: 0 }` skips the platform history lookup Mastra runs when an agent is first mentioned in a group chat, which the adapter can't perform. Both override defaults that assume platform features iMessage lacks.
+`toolDisplay: 'text'` describes tool calls in the message, since iMessage has no interactive cards for Approve and Deny actions. Both adapters need it: Photon has no card rendering, and Linq flattens cards to plain text where buttons show their labels but can't trigger actions.
+
+> **Warning:** Text rendering can't submit approval decisions. A tool with `requireApproval: true` stays suspended until a UI or API action, such as Studio, submits an explicit approval or decline, so avoid approval-gated tools on iMessage agents unless another surface handles the decision. See [Tool approval](https://mastra.ai/docs/channels).
 
 ## Adapter setup
 
+**Photon**:
+
 Follow the [Photon iMessage adapter docs](https://github.com/photon-hq/vercel-chat-adapter-imessage) for iMessage-specific setup, including number provisioning, hosted and self-hosted modes, and webhook registration. The adapter picks its mode from the environment variables you set.
 
 For the hosted service, create a project at [app.photon.codes](https://app.photon.codes) and use the project credentials:
@@ -94,6 +214,17 @@ IMESSAGE_PHONE=+15551234567
 
 `IMESSAGE_PHONE` is optional and routes messages when a self-hosted server has several numbers. You can also pass these values to `createiMessageAdapter()` directly, including a `credentials` function that resolves the project ID and secret at first use from a secret store.
 
+**Linq**:
+
+Follow the [Linq API docs](https://docs.linqapp.com/) for Linq-specific setup, including phone number provisioning and API keys. Create a Linq account, copy your API key, and set the credentials the agent configuration reads:
+
+```bash
+LINQ_API_KEY=your-linq-api-key
+LINQ_WEBHOOK_SECRET=your-webhook-signing-secret
+```
+
+`LINQ_WEBHOOK_SECRET` is the signing secret returned when you create a webhook subscription in the next section. The adapter also accepts a `baseURL` option to target a different Linq API base URL, such as a sandbox.
+
 ## Webhook URL
 
 Mastra generates the iMessage webhook route from the agent ID and adapter key:
@@ -108,13 +239,25 @@ Use your public Mastra server URL as the base URL:
 https://your-app.example.com/api/agents/imessage-agent/channels/imessage/webhook
 ```
 
+**Photon**:
+
 Register this URL in the [Photon dashboard](https://app.photon.codes), then set the signing secret it returns as `IMESSAGE_WEBHOOK_SECRET`. The secret is shown once at registration. The adapter verifies the signature on every delivery and rejects requests that don't match. Webhooks are available in hosted mode only.
 
-> **Note:** Photon delivers to public HTTPS endpoints only. It won't deliver to `http://`, to private addresses like `localhost`, or through a redirect. For local development, use a tunnel as described in the [Channels overview](https://mastra.ai/docs/channels).
+**Linq**:
+
+Create a [webhook subscription](https://docs.linqapp.com/guides/webhooks/subscriptions/) with this URL as the target and subscribe to at least these events:
+
+- `message.received`
+- `reaction.added`
+- `reaction.removed`
+
+Set the `signing_secret` the subscription returns as `LINQ_WEBHOOK_SECRET`. The secret is shown once at creation and can't be retrieved later. The adapter verifies the HMAC signature on every delivery, checks for replayed requests, and rejects requests that don't match.
+
+> **Note:** Both providers deliver to public HTTPS endpoints only, not to `http://` or private addresses like `localhost`. For local development, use a tunnel as described in the [Channels overview](https://mastra.ai/docs/channels).
 
 ## Duplicate deliveries
 
-Photon retries failed deliveries with backoff and delivers at least once, so the same message can arrive twice. Chat SDK drops the repeat using the channel state adapter, and Mastra's default keeps those dedup keys in memory. That covers a single long-running server.
+Photon and Linq retry failed deliveries with backoff and deliver at least once, so the same message can arrive twice. Chat SDK drops the repeat using the channel state adapter, and Mastra's default keeps those dedup keys in memory. That covers a single long-running server.
 
 A repeat can still reach the agent after a restart, or on serverless where the retry is routed to a different instance. Pass a shared state adapter on `channels.state` so dedup keys are visible everywhere. Install one alongside the adapter:
 
@@ -154,7 +297,6 @@ channels: {
       toolDisplay: 'text',
     },
   },
-  threadContext: { maxMessages: 0 },
   state: createRedisState(),
 },
 ```
@@ -163,13 +305,13 @@ This matters most for tools with side effects, where handling the same message t
 
 ## Read receipts
 
-iPhone Messages sends a read receipt for every message the agent posts, and the adapter delivers those receipts as inbound messages with no text and no attachments. Mastra skips them, so the agent doesn't answer its own reply in a loop. Their message IDs carry a `:read:` suffix, and they show up as skipped messages at `debug` log level.
+iPhone Messages sends a read receipt for every message the agent posts, and the Photon adapter delivers those receipts as inbound messages with no text and no attachments. Mastra skips them, so the agent doesn't answer its own reply in a loop. Their message IDs carry a `:read:` suffix, and they show up as skipped messages at `debug` log level.
 
 The same rule applies to every adapter: an inbound message with neither text nor attachments never starts an agent run. A custom `onDirectMessage`, `onMention`, or `onSubscribedMessage` handler still receives it and can act on it before calling `defaultHandler`.
 
 ## Gateway listener
 
-The adapter can hold an open connection and stream messages in real time instead of receiving webhooks. This works in both hosted and self-hosted modes.
+The Photon adapter can hold an open connection and stream messages in real time instead of receiving webhooks. This works in both hosted and self-hosted modes. The Linq adapter is webhook-driven and has no gateway mode.
 
 Mastra starts this listener during initialization and reconnects it if it drops, so no cron job or extra route is needed on a long-running server. Set `gateway: false` on the adapter config to turn it off when you use webhooks: