## Summary
Agents can now dispatch slow tool calls to run asynchronously while the
conversation keeps streaming. The LLM receives a placeholder result
immediately and continues generating; when the background tool finishes,
its result flows back into the loop (if still open) or the message list
for the LLM to process when queried.
```
User: "Research Solana for me, and what's Bitcoin's price?"
Agent: crypto-price runs synchronously → "Bitcoin is at $68,434"
crypto-research dispatched to background → "I'm researching Solana…"
(stream closes, UI shows 1 background task running)
when background task is done, result is injected into the agent message list
UI shows 1 background task compeleted
//User can ask agent other question and even when background task is still running
User: what's the result of the research
Agent: agent processes solana research result → full analysis
```
## Architecture
Three subsystems working together:
1. **PubSub** (reuses the existing workflows pubsub) — two topics:
- `background-tasks` with group subscription so workers compete for each
dispatch / cancel message (only one worker picks up each task)
- `background-tasks-result` with fan-out so every process hears
lifecycle events (`task.running`, `task.completed`, `task.failed`,
`task.cancelled`, `task.output`)
Retries are delegated to the pubsub layer via `nack()` +
`deliveryAttempt` tracking — no manual re-dispatch on the manager.
2. **Storage** — new `BackgroundTasksStorage` domain. `TaskFilter`
supports status, agent / thread / resource / run / tool filters, date
range (`fromDate` / `toDate` / `dateFilterBy`), ordering, and pagination
(`page` / `perPage`). `listTasks()` returns `{ tasks, total }`.
3. **Agentic loop** — `tool-call-step` resolves bg config (LLM
`_background` override → agent → tool → manager defaults), dispatches
via `createBackgroundTask()`, and returns a placeholder.
`backgroundTaskCheckStep` pauses the loop between LLM iterations with
configurable `waitTimeoutMs` (Strategy B — process results as they
arrive). `isTaskCompleteStep` skips scoring while a task is still
pending.
## Key features
- **`createBackgroundTask(manager, options)`** — self-contained per-task
handle with `dispatch()`, `cancel()`, `waitForCompletion()`. Per-task
`TaskContext` (executor, `onChunk`, `onResult`, `onComplete`,
`onFailed`) is keyed by task ID so concurrent streams never share state.
- **Schema + prompt injection** — `_background` field added to
bg-eligible tool schemas (both JSON Schema and Zod) + generated system
prompt section listing bg-eligible tools and defaults.
- **HTTP API** — `/api/background-tasks/stream` (SSE),
`/api/background-tasks` (list with filters + pagination),
`/api/background-tasks/:taskId` (get by ID). The SSE route uses a
snapshot-then-tail pattern so clients can connect at any time and
receive the current state of running tasks before tailing live events.
- **Client SDK** — `client.listBackgroundTasks`,
`client.getBackgroundTask`, `client.streamBackgroundTasks` on
`MastraClient`.
- **Playground hook** — `useBackgroundTaskStream` accumulates events in
a `Record<taskId, BackgroundTaskEvent>` map with `runningTasks` /
`completedTasks` / `failedTasks` derivations. Wired into the studio so
users are notified when bg tool calls finish.
- **Progress streaming** — executor receives `onProgress(chunk)` for
tools that emit intermediate `tool-output` chunks during long-running
execution.
- **Recovery** — on startup, stale `running` tasks reset to pending (if
retries remain) or marked failed; orphaned `pending` tasks
re-dispatched.
- **Cleanup** — configurable TTLs for completed / failed task records
with a periodic interval.
- **Concurrency** — global + per-agent limits with `queue` / `reject` /
`fallback-sync` backpressure strategies.
- **Sub-agent awareness** — `listAgentTools` derives a
`ToolBackgroundConfig` from sub-agents whose tools or config enable
background execution, so the parent can dispatch the sub-agent
invocation itself as a background task. New
`agent.disableBackgroundTasks()` / `enableBackgroundTasks()` so a
sub-agent wrapped as a bg task doesn't also dispatch its own tools as
additional bg tasks.
## Configuration
Four levels, with the LLM override always winning:
```
LLM _background override in tool args ← highest priority
↓
Agent backgroundTasks.tools config
↓
Tool background config
↓
Manager defaults
↓
Default: foreground, 5min timeout, 0 retries ← lowest priority
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5 (Explain Like I'm 5)
This PR lets AI agents start slow tasks (like long web research) in the
background and keep talking to the user immediately. The agent returns a
small placeholder now, the background task runs separately, and its real
result is injected back into the conversation when it's ready.
---
## Summary
This PR implements a full background-task execution system for agents
that enables long-running tool calls to run asynchronously while
conversations continue streaming. It touches agent orchestration,
pub/sub, storage, HTTP APIs, client SDKs, UI/playground, and multiple
storage adapters.
Key components
- BackgroundTaskManager: queueing, dispatch, execution, retries,
cancellation, lifecycle events, concurrency controls (global +
per-agent), cleanup TTLs, startup recovery, streaming, and shutdown.
- Storage domain: new BackgroundTasksStorage abstraction with
list/filter/pagination; implementations added for InMemory, Postgres,
MongoDB, DynamoDB, LibSQL, MSSQL, ClickHouse, Cloudflare D1/DO/KV,
Convex, LanceDB, Upstash/Redis.
- Pub/Sub: reuses workflows pubsub with two topics (grouped
`background-tasks` for dispatch/cancel; fan-out
`background-tasks-result` for lifecycle events), adds deliveryAttempt
tracking and nack/redelivery; EventEmitterPubSub and Google Cloud PubSub
updated for grouped subscriptions and exactly-once semantics.
- Agent loop integration: tool-call-step resolves background config
(priority: per-call LLM _background override → agent → tool → manager),
creates per-task handles (dispatch/cancel/waitForCompletion), dispatches
tasks and returns placeholders; backgroundTaskCheckStep waits between
LLM iterations (configurable waitTimeoutMs, process-as-arrive strategy);
isTaskCompleteStep skips scoring while background pending; system prompt
and schema injection add optional _background per-call override.
- APIs and SDKs: server endpoints GET /api/background-tasks/stream (SSE
snapshot-then-tail), GET /api/background-tasks (list with
filters/pagination), GET /api/background-tasks/:taskId; MastraClient
additions: listBackgroundTasks, getBackgroundTask, streamBackgroundTasks
(robust SSE parsing).
- Playground & UI: useBackgroundTaskStream hook, thread/composer badges
showing running/completed/failed counts, tooling UI adjustments
(ToolBadge withoutArgs, tool-fallback handling).
- Types & stream chunks: new BackgroundTask types and agent chunk
variants: background-task-started, -completed, -failed, -progress; UI
metadata field runningBackgroundTasksCount updated accordingly.
- Examples & tests: example cryptoResearchAgent/cryptoPriceTool;
comprehensive tests added for manager, storage domains, server handlers,
client, pubsub group behavior, and end-to-end background task flows.
Defaults and behavior
- Background dispatch is opt-in (foreground by default).
- Default timeout: 5 minutes (300_000 ms); default retries: 0.
- Backpressure strategies: queue / reject / fallback-sync.
- Per-task context supports onProgress streaming, onResult injection,
and onComplete/onFailed callbacks.
Files and scope
- Adds background-tasks domain under packages/core and new storage
domains across multiple stores, updates pubsub implementations,
agent/workflow loop changes, server routes/schemas, client SDK
methods/tests, playground hook/UI, changesets, and a dev docker-compose
pubsub emulator for testing.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds `vectorType` option to PgVector's `createIndex()` for choosing
between full precision (`vector`) and half precision (`halfvec`)
storage.
Fixes#10999.
halfvec uses 2 bytes per dimension instead of 4, allowing indexes on
embeddings up to 4000 dimensions. Useful for models like
`text-embedding-3-large` (3072 dimensions).
```typescript
await pgVector.createIndex({
indexName: 'large-embeddings',
dimension: 3072,
metric: 'cosine',
vectorType: 'halfvec',
});
```
Also updates docker-compose files to use pgvector 0.8.0 (halfvec
requires >= 0.7.0).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added halfvec support for half-precision embeddings (2-byte dims),
enabling indexes up to 4,000 dimensions.
* Introduced optional vectorType parameter to choose 'vector' or
'halfvec' for an index.
* Index metadata (describe/list) now reports the selected vectorType.
* **Bug Fixes / Validation**
* Added validation and clear error when halfvec is requested but not
supported.
* **Tests**
* Added comprehensive tests for halfvec detection, index creation,
queries, and operator selection.
* **Chores**
* Updated local Docker Compose pgvector image to 0.8.0 for halfvec
compatibility.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: NikAiyer <nick.aiyer@gmail.com>