@mastra/mcp-docs-server 1.1.42 → 1.1.43-alpha.0

package/.docs/reference/cli/mastra.md

@@ -603,10 +603,10 @@ It accepts [common flags](#common-flags).
 Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, self-hosted Mastra servers, or hosted Mastra Platform Observability APIs.
 
 ```bash
-mastra api agent list --pretty
+mastra api agent list
 mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
 mastra api tool execute get-weather '{"location":"San Francisco"}'
-mastra api trace list '{"page":0,"perPage":20}' --pretty
+mastra api trace list '{"page":0,"perPage":20}'
 ```
 
 Use `mastra api <resource> <action> --help` to see examples for a command.
@@ -717,7 +717,7 @@ mastra api trace list '{"page":0,"perPage":20}'
 Routes that support filters accept them in the same JSON input. For example, observability trace listing supports pagination and route-supported filters:
 
 ```bash
-mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}' --pretty
+mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}'
 ```
 
 ### Get command-specific help
@@ -973,8 +973,8 @@ Lists observability traces. Pass optional JSON input for route-supported filters
 
 ```bash
 mastra api trace list [input]
-mastra api trace list '{"page":0,"perPage":20}' --pretty
-mastra api trace list '{"page":0,"perPage":20}' --verbose --pretty
+mastra api trace list '{"page":0,"perPage":20}'
+mastra api trace list '{"page":0,"perPage":20}' --verbose
 ```
 
 `trace list` returns lightweight root span records by default so you can page through traces without fetching large input, output, attributes, or metadata payloads. Pass `--verbose` to fetch the full root span records.

package/.docs/reference/client-js/agents.md

@@ -151,17 +151,51 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `sendMessage()`
+
+Send user-authored input to an active agent run or idle memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the message.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const result = await agent.sendMessage({
+  message: {
+    contents: 'Also consider the customer note I just added.',
+    attributes: { sentFrom: 'web' },
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+console.log(result.runId)
+```
+
+`message` accepts a string, an array of text/file parts, or an object with `contents`, `attributes`, `metadata`, and `providerOptions`.
+
+### `queueMessage()`
+
+Queue user-authored input for the next thread turn. If the thread is active, Mastra starts a new run after the current run completes. If the thread is idle, Mastra starts a run immediately.
+
+```typescript
+await agent.queueMessage({
+  message: 'Also check whether the tests need updates.',
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+```
+
 ### `sendSignal()`
 
-Send a signal to an active agent run or memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the signal.
+Send a lower-level signal to an active agent run or memory thread. Use this for system-generated context such as reactive reminders or notification-shaped context that doesn't need inbox storage. For durable notification records, use the server-side [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent) API. For user-authored input, prefer `sendMessage()` or `queueMessage()`.
 
 ```typescript
 const agent = mastraClient.getAgent('support-agent')
 
 const result = await agent.sendSignal({
   signal: {
-    type: 'user-message',
-    contents: 'Also consider the customer note I just added.',
+    type: 'reactive',
+    tagName: 'system-reminder',
+    contents: 'Also consider the latest customer note.',
   },
   resourceId: 'user-123',
   threadId: 'thread-abc',
@@ -174,7 +208,7 @@ Use `ifActive.behavior` and `ifIdle.behavior` to control whether Mastra delivers
 
 ```typescript
 await agent.sendSignal({
-  signal: { type: 'user-message', contents: 'Store this for later.' },
+  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Store this for later.' },
   resourceId: 'user-123',
   threadId: 'thread-abc',
   ifIdle: {
@@ -187,7 +221,7 @@ Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as m
 
 ```typescript
 await agent.sendSignal({
-  signal: { type: 'user-message', contents: 'Start from this signal.' },
+  signal: { type: 'reactive', tagName: 'system-reminder', contents: 'Start from this signal.' },
   resourceId: 'user-123',
   threadId: 'thread-abc',
   ifIdle: {
@@ -201,7 +235,7 @@ await agent.sendSignal({
 
 Returns `{ accepted: true, runId: string }`.
 
-**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user' | 'reactive' | 'notification' | string; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Lower-level signal payload. Use \`type\` for the semantic signal category and \`tagName\` for the XML tag shown to the model. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
 
 **runId** (`string`): Run ID to target directly.
 
@@ -217,7 +251,7 @@ Returns `{ accepted: true, runId: string }`.
 
 ### `subscribeToThread()`
 
-Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendSignal()`.
+Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendMessage()`, `queueMessage()`, `sendSignal()`, or server-side notification dispatch.
 
 ```typescript
 const agent = mastraClient.getAgent('support-agent')

package/.docs/reference/index.md

@@ -2,8 +2,11 @@
 
 The Reference section provides documentation of Mastra's API, including parameters, types and usage examples.
 
+- [AcpAgent](https://mastra.ai/reference/acp/acp-agent)
+- [createACPTool()](https://mastra.ai/reference/acp/create-acp-tool)
 - [Agent Class](https://mastra.ai/reference/agents/agent)
 - [Channels](https://mastra.ai/reference/agents/channels)
+- [DurableAgent](https://mastra.ai/reference/agents/durable-agent)
 - [.generate()](https://mastra.ai/reference/agents/generate)
 - [.generateLegacy()](https://mastra.ai/reference/agents/generateLegacy)
 - [.getDefaultGenerateOptionsLegacy()](https://mastra.ai/reference/agents/getDefaultGenerateOptions)
@@ -193,6 +196,12 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [UnicodeNormalizer](https://mastra.ai/reference/processors/unicode-normalizer)
 - [WorkingMemory](https://mastra.ai/reference/processors/working-memory-processor)
+- [CachingPubSub](https://mastra.ai/reference/pubsub/caching-pubsub)
+- [EventEmitterPubSub](https://mastra.ai/reference/pubsub/event-emitter)
+- [GoogleCloudPubSub](https://mastra.ai/reference/pubsub/google-cloud-pubsub)
+- [PubSub](https://mastra.ai/reference/pubsub/base)
+- [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams)
+- [UnixSocketPubSub](https://mastra.ai/reference/pubsub/unix-socket-pubsub)
 - [DatabaseConfig](https://mastra.ai/reference/rag/database-config)
 - [Embed](https://mastra.ai/reference/rag/embeddings)
 - [ExtractParams](https://mastra.ai/reference/rag/extract-params)

package/.docs/reference/processors/response-cache.md

@@ -34,7 +34,7 @@ await agent.generate('What is the capital of France?', {
 })
 ```
 
-See [Response caching](https://mastra.ai/docs/agents/response-caching) for the conceptual overview, scoping rules, and recommended deployment patterns.
+See [Response caching](https://mastra.ai/docs/agents/processors) for the conceptual overview, scoping rules, and recommended deployment patterns.
 
 ## Constructor parameters
 
@@ -109,6 +109,6 @@ The argument passed to a `key` function (constructor or per-call). All fields co
 
 ## Related
 
-- [Response caching](https://mastra.ai/docs/agents/response-caching)
+- [Response caching](https://mastra.ai/docs/agents/processors)
 - [Processors](https://mastra.ai/docs/agents/processors)
 - [Processor interface](https://mastra.ai/reference/processors/processor-interface)

package/.docs/reference/pubsub/base.md

@@ -0,0 +1,168 @@
+# PubSub
+
+`PubSub` is the abstract base class for Mastra's event system. It defines the contract that every pub/sub backend implements, so the rest of Mastra can publish and subscribe to events without knowing which transport is in use.
+
+Mastra uses pub/sub internally for workflow event processing, streaming, and cross-component communication. Most applications use the default [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter) and never construct a `PubSub` directly. Implement this class only when you need a custom transport.
+
+For built-in implementations, see [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter), [`UnixSocketPubSub`](https://mastra.ai/reference/pubsub/unix-socket-pubsub), [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub), [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), and [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
+
+## Usage example
+
+Extend `PubSub` and implement the four abstract methods to add a custom backend.
+
+```typescript
+import { PubSub } from '@mastra/core/events'
+import type { Event, EventCallback, SubscribeOptions } from '@mastra/core/events'
+
+export class CustomPubSub extends PubSub {
+  async publish(topic: string, event: Omit<Event, 'id' | 'createdAt'>): Promise<void> {
+    // Deliver the event to subscribers of `topic`.
+  }
+
+  async subscribe(topic: string, cb: EventCallback, options?: SubscribeOptions): Promise<void> {
+    // Register `cb` to receive events published to `topic`.
+  }
+
+  async unsubscribe(topic: string, cb: EventCallback): Promise<void> {
+    // Remove a previously registered callback.
+  }
+
+  async flush(): Promise<void> {
+    // Wait for any in-flight deliveries to settle.
+  }
+}
+```
+
+Pass the instance to the [Mastra](https://mastra.ai/reference/core/mastra-class) constructor:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { CustomPubSub } from './pubsub'
+
+export const mastra = new Mastra({
+  pubsub: new CustomPubSub(),
+})
+```
+
+## Delivery modes
+
+A `PubSub` declares which delivery modes it supports through the `supportedModes` property. Mastra reads this to decide whether to run a long-lived worker that pulls events.
+
+| Mode   | Description                                                                                                                   |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `pull` | Consumers actively read from the broker, for example Redis Streams `XREADGROUP`. Mastra runs an orchestration worker to read. |
+| `push` | Events arrive without the consumer asking, either in-process or through an HTTP endpoint. No read loop is required.           |
+
+The default is `['pull']` so that custom implementations keep today's behavior unless they opt in to push delivery.
+
+## Methods
+
+### Core methods
+
+#### `publish(topic, event)`
+
+Publishes an event to a topic. The `id` and `createdAt` fields are assigned by the implementation.
+
+```typescript
+await pubsub.publish('my-topic', {
+  type: 'example',
+  data: { value: 1 },
+  runId: 'run-123',
+})
+```
+
+#### `subscribe(topic, cb, options?)`
+
+Registers a callback to receive events published to a topic. When `options.group` is set, subscribers in the same group compete for messages and each event is delivered to one member. Without a group, every subscriber receives every event.
+
+```typescript
+await pubsub.subscribe('my-topic', (event, ack, nack) => {
+  console.log(event)
+})
+```
+
+#### `unsubscribe(topic, cb)`
+
+Removes a previously registered callback from a topic.
+
+```typescript
+await pubsub.unsubscribe('my-topic', callback)
+```
+
+#### `flush()`
+
+Waits for any in-flight deliveries to settle. Call this before shutdown to avoid dropping events.
+
+```typescript
+await pubsub.flush()
+```
+
+### Replay methods
+
+These methods support resuming a stream after a disconnect. The default implementations fall back to a regular `subscribe`, so backends without history support behave as live-only. [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) overrides them to replay cached events.
+
+#### `getHistory(topic, offset?)`
+
+Returns cached events for a topic, starting at `offset`. Returns an empty array when the backend has no history.
+
+```typescript
+const events = await pubsub.getHistory('my-topic', 0)
+```
+
+Returns: `Promise<Event[]>`
+
+#### `subscribeWithReplay(topic, cb)`
+
+Replays cached events, then subscribes to live events.
+
+```typescript
+await pubsub.subscribeWithReplay('my-topic', event => {
+  console.log(event)
+})
+```
+
+#### `subscribeFromOffset(topic, offset, cb)`
+
+Replays cached events starting at a known position, then subscribes to live events. This is more efficient than a full replay when the client knows its last position.
+
+```typescript
+await pubsub.subscribeFromOffset('my-topic', 42, event => {
+  console.log(event)
+})
+```
+
+## Properties
+
+**supportedModes** (`ReadonlyArray<"pull" | "push">`): Delivery modes the implementation supports. Defaults to \`\["pull"]\`.
+
+## Types
+
+### `Event`
+
+**type** (`string`): Event type identifier.
+
+**id** (`string`): Unique event ID, assigned by the implementation on publish.
+
+**data** (`any`): Event payload.
+
+**runId** (`string`): Run the event belongs to.
+
+**createdAt** (`Date`): Timestamp assigned by the implementation on publish.
+
+**index** (`number`): Sequential position used to resume from a specific offset.
+
+**deliveryAttempt** (`number`): Number of times the event has been delivered. Starts at 1. Defaults to 1 when the backend does not track redelivery.
+
+### `SubscribeOptions`
+
+**group** (`string`): When set, subscribers with the same group compete for messages and each event is delivered to one member. When omitted, every subscriber receives every event.
+
+### `EventCallback`
+
+The callback signature for subscribers: `(event: Event, ack?: () => Promise<void>, nack?: () => Promise<void>) => void`.
+
+**event** (`Event`): The delivered event.
+
+**ack** (`() => Promise<void>`): Acknowledge successful processing. The event is removed from the queue.
+
+**nack** (`() => Promise<void>`): Negative acknowledge. The event is requeued for redelivery after a delay.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -0,0 +1,102 @@
+# CachingPubSub
+
+`CachingPubSub` wraps any [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation and adds event caching and replay. It records every published event per topic in a cache, so a subscriber that connects late or reconnects after a disconnect can replay the events it missed before continuing with live events.
+
+Use it to build resumable streams on top of a transport that does not keep history, such as [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). Transports that already persist events, such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), do not need this wrapper.
+
+## Usage example
+
+Wrap an inner pub/sub and provide a server cache to store events.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { CachingPubSub, EventEmitterPubSub } from '@mastra/core/events'
+import { InMemoryServerCache } from '@mastra/core/cache'
+
+const cache = new InMemoryServerCache()
+const pubsub = new CachingPubSub(new EventEmitterPubSub(), cache)
+
+export const mastra = new Mastra({
+  pubsub,
+})
+```
+
+The `withCaching` helper returns the same instance and reads better when wrapping inline:
+
+```typescript
+import { withCaching, EventEmitterPubSub } from '@mastra/core/events'
+import { InMemoryServerCache } from '@mastra/core/cache'
+
+const pubsub = withCaching(new EventEmitterPubSub(), new InMemoryServerCache())
+```
+
+## Constructor parameters
+
+**inner** (`PubSub`): The pub/sub implementation to wrap. All publishes and live subscriptions pass through to this instance.
+
+**cache** (`MastraServerCache`): Cache used to store events per topic for replay.
+
+**options** (`CachingPubSubOptions`): Optional configuration.
+
+## Methods
+
+`CachingPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. It overrides the replay methods to read cached events. The methods below describe the caching behavior.
+
+### `publish(topic, event)`
+
+Caches the event with a sequential index, then publishes it to the inner pub/sub.
+
+```typescript
+await pubsub.publish('my-topic', {
+  type: 'example',
+  data: { value: 1 },
+  runId: 'run-123',
+})
+```
+
+### `subscribeWithReplay(topic, cb)`
+
+Replays all cached events for the topic, then subscribes to live events.
+
+```typescript
+await pubsub.subscribeWithReplay('my-topic', event => {
+  console.log(event)
+})
+```
+
+### `subscribeFromOffset(topic, offset, cb)`
+
+Replays cached events starting at `offset`, then subscribes to live events. Use this when the client knows its last position, to avoid replaying the whole history.
+
+```typescript
+await pubsub.subscribeFromOffset('my-topic', 42, event => {
+  console.log(event)
+})
+```
+
+### `getHistory(topic, offset?)`
+
+Returns cached events for the topic, starting at `offset`.
+
+```typescript
+const events = await pubsub.getHistory('my-topic', 0)
+```
+
+Returns: `Promise<Event[]>`
+
+## Functions
+
+### `withCaching(pubsub, cache, options?)`
+
+Convenience wrapper that constructs a `CachingPubSub`. Accepts the same arguments as the constructor and returns the new instance.
+
+```typescript
+import { withCaching, EventEmitterPubSub } from '@mastra/core/events'
+import { InMemoryServerCache } from '@mastra/core/cache'
+
+const pubsub = withCaching(new EventEmitterPubSub(), new InMemoryServerCache(), {
+  keyPrefix: 'events:',
+})
+```
+
+Returns: `CachingPubSub`

package/.docs/reference/pubsub/event-emitter.md

@@ -0,0 +1,72 @@
+# EventEmitterPubSub
+
+`EventEmitterPubSub` is the default [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation. It delivers events in-process using a Node.js [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter), so it works without any external service.
+
+Use it for single-process applications. For delivery across processes on one host, see [`UnixSocketPubSub`](https://mastra.ai/reference/pubsub/unix-socket-pubsub). For distributed delivery, see [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
+
+Because it is in-process, events are not persisted and are not shared with other processes. Wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) when you need replay for resumable streams.
+
+## Usage example
+
+`EventEmitterPubSub` is used automatically when you do not configure a `pubsub` option, so most applications never construct it directly. Create one explicitly only when you want to configure or share it.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { EventEmitterPubSub } from '@mastra/core/events'
+
+export const mastra = new Mastra({
+  pubsub: new EventEmitterPubSub(),
+})
+```
+
+To share an emitter with other parts of your application, pass an existing `EventEmitter`:
+
+```typescript
+import EventEmitter from 'node:events'
+import { EventEmitterPubSub } from '@mastra/core/events'
+
+const emitter = new EventEmitter()
+const pubsub = new EventEmitterPubSub(emitter)
+```
+
+## Constructor parameters
+
+**existingEmitter** (`EventEmitter`): An existing Node.js EventEmitter to use for delivery. When omitted, a new EventEmitter is created.
+
+## Properties
+
+**supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \`\["pull", "push"]\`. The emitter can serve a pull-style worker or push events directly to listeners.
+
+## Methods
+
+`EventEmitterPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
+
+### `subscribe(topic, cb, options?)`
+
+Registers a callback for a topic. Without `options.group`, every subscriber receives every event. With a group, events are distributed round-robin across members of that group.
+
+```typescript
+await pubsub.subscribe('workflow.events', (event, ack, nack) => {
+  console.log(event)
+})
+```
+
+### `flush()`
+
+Waits for any pending redeliveries from `nack` to fire before resolving.
+
+```typescript
+await pubsub.flush()
+```
+
+### `close()`
+
+Removes all listeners and cancels pending redeliveries. Call this during graceful shutdown.
+
+```typescript
+await pubsub.close()
+```
+
+## Redelivery
+
+When a grouped subscriber calls `nack`, the event is redelivered to the group after a short delay, and its `deliveryAttempt` count increases. Calling `ack` clears the tracking for that event. Fan-out subscribers receive no-op `ack` and `nack` functions, since each event reaches every subscriber once.

package/.docs/reference/pubsub/google-cloud-pubsub.md

@@ -0,0 +1,94 @@
+# GoogleCloudPubSub
+
+`GoogleCloudPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs). It delivers events across processes and hosts using Google Cloud topics and subscriptions, with ordered delivery and message acknowledgment.
+
+Use it for distributed deployments on Google Cloud. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For Redis, use [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams).
+
+Each topic maps to a Google Cloud topic. Subscriptions with a group share a named subscription, so members compete for events. Subscriptions without a group create a per-instance subscription, so every instance receives every event.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/google-cloud-pubsub
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/google-cloud-pubsub
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/google-cloud-pubsub
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/google-cloud-pubsub
+```
+
+## Usage example
+
+Pass a Google Cloud client configuration, such as a project ID.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
+
+export const mastra = new Mastra({
+  pubsub: new GoogleCloudPubSub({
+    projectId: 'my-project',
+  }),
+})
+```
+
+## Constructor parameters
+
+**config** (`ClientConfig`): Configuration for the Google Cloud Pub/Sub client, including credentials and project ID. See the \`@google-cloud/pubsub\` client documentation for all fields.
+
+## Methods
+
+`GoogleCloudPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below are specific to this implementation.
+
+### `init(topicName, group?)`
+
+Creates the topic and a subscription if they do not already exist, and returns the subscription. `subscribe` calls this internally, so you rarely call it directly.
+
+```typescript
+await pubsub.init('workflow.events')
+```
+
+### `subscribe(topic, cb, options?)`
+
+Subscribes to a topic. With `options.group`, members of the group share a subscription and compete for events. Without a group, the instance receives every event through its own subscription.
+
+```typescript
+await pubsub.subscribe('workflow.events', (event, ack, nack) => {
+  console.log(event)
+})
+```
+
+### `flush()`
+
+Waits for pending acknowledgments to complete.
+
+```typescript
+await pubsub.flush()
+```
+
+### `destroy(topicName)`
+
+Removes the subscription and topic for a given topic name. Use this to clean up Google Cloud resources.
+
+```typescript
+await pubsub.destroy('workflow.events')
+```
+
+## Acknowledgment
+
+Each delivered event includes `ack` and `nack` functions. Call `ack` after successful processing to remove the event from the subscription. When neither is called, Google Cloud redelivers the event after its acknowledgment deadline expires.