@mastra/libsql 0.0.0-working-memory-undefined-20260212204651 → 0.0.0-workshop-yj-20260903030708

package/dist/docs/references/docs-agents-network-approval.md

@@ -1,275 +0,0 @@
-# Network Approval
-
-Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in individual agents and workflows. When a tool, subagent, or workflow within a network requires approval or suspends execution, the network pauses and emits events that allow your application to collect user input before resuming.
-
-## Storage
-
-Network approval uses snapshots to capture execution state. Ensure you've enabled a storage provider in your Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
-
-```typescript
-import { Mastra } from "@mastra/core/mastra";
-import { LibSQLStore } from "@mastra/libsql";
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: "mastra-storage",
-    url: ":memory:"
-  })
-});
-```
-
-## Approving network tool calls
-
-When a tool within a network has `requireApproval: true`, the network stream emits an `agent-execution-approval` chunk and pauses. To allow the tool to execute, call `approveNetworkToolCall` with the `runId`.
-
-```typescript
-const stream = await routingAgent.network("Process this query", {
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-let runId: string;
-
-for await (const chunk of stream) {
-  runId = stream.runId;
-  // if the requirApproval is in a tool inside a subAgent or the subAgent has requireToolApproval set to true
-  if (chunk.type === "agent-execution-approval") {
-    console.log("Tool requires approval:", chunk.payload);
-  }
-
-  // if the requirApproval is in a tool directly in the network agent
-  if (chunk.type === "tool-execution-approval") {
-    console.log("Tool requires approval:", chunk.payload);
-  }
-}
-
-// Approve and resume execution
-const approvedStream = await routingAgent.approveNetworkToolCall({
-  runId,
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-for await (const chunk of approvedStream) {
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-
-## Declining network tool calls
-
-To decline a pending tool call and prevent execution, call `declineNetworkToolCall`. The network continues without executing the tool.
-
-```typescript
-const declinedStream = await routingAgent.declineNetworkToolCall({
-  runId,
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-for await (const chunk of declinedStream) {
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-
-## Resuming suspended networks
-
-When a primitive in the network calls `suspend()`, the stream emits an `agent-execution-suspended`/`tool-execution-suspended`/`workflow-execution-suspended` chunk with a `suspendPayload` containing context from the primitive. Use `resumeNetwork` to provide the data requested by the primitive and continue execution.
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-const confirmationTool = createTool({
-  id: "confirmation-tool",
-  description: "Requests user confirmation before proceeding",
-  inputSchema: z.object({
-    action: z.string()
-  }),
-  outputSchema: z.object({
-    confirmed: z.boolean(),
-    action: z.string()
-  }),
-  suspendSchema: z.object({
-    message: z.string(),
-    action: z.string()
-  }),
-  resumeSchema: z.object({
-    confirmed: z.boolean()
-  }),
-  execute: async (inputData, context) => {
-    const { resumeData, suspend } = context?.agent ?? {};
-
-    if (!resumeData?.confirmed) {
-      return suspend?.({
-        message: `Please confirm: ${inputData.action}`,
-        action: inputData.action
-      });
-    }
-
-    return { confirmed: true, action: inputData.action };
-  }
-});
-```
-
-Handle the suspension and resume with user-provided data:
-
-```typescript
-const stream = await routingAgent.network("Delete the old records", {
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-for await (const chunk of stream) {
-  if (chunk.type === "workflow-execution-suspended") {
-    console.log(chunk.payload.suspendPayload);
-    // { message: "Please confirm: delete old records", action: "delete old records" }
-  }
-}
-
-// Resume with user confirmation
-const resumedStream = await routingAgent.resumeNetwork(
-  { confirmed: true },
-  {
-    runId: stream.runId,
-    memory: {
-      thread: "user-123",
-      resource: "my-app"
-    }
-  }
-);
-
-for await (const chunk of resumedStream) {
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-
-## Automatic primitive resumption
-
-When using primitives that call `suspend()`, you can enable automatic resumption so the network resumes suspended primitives based on the user's next message. This creates a conversational flow where users provide the required information naturally.
-
-### Enabling auto-resume
-
-Set `autoResumeSuspendedTools` to `true` in the agent's `defaultNetworkOptions` or when calling `network()`:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-
-// Option 1: In agent configuration
-const routingAgent = new Agent({
-  id: "routing-agent",
-  name: "Routing Agent",
-  instructions: "You coordinate tasks across multiple agents",
-  model: "openai/gpt-4o-mini",
-  tools: { confirmationTool },
-  memory: new Memory(),
-  defaultNetworkOptions: {
-    autoResumeSuspendedTools: true,
-  },
-});
-
-// Option 2: Per-request
-const stream = await routingAgent.network("Process this request", {
-  autoResumeSuspendedTools: true,
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-```
-
-### How it works
-
-When `autoResumeSuspendedTools` is enabled:
-
-1. A primitive suspends execution by calling `suspend()` with a payload
-
-2. The suspension is persisted to memory along with the conversation
-
-3. When the user sends their next message on the same thread, the network:
-
-   - Detects the suspended primitive from message history
-   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
-   - Automatically resumes the primitive with the extracted data
-
-### Example
-
-```typescript
-const stream = await routingAgent.network("Delete the old records", {
-  autoResumeSuspendedTools: true,
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-for await (const chunk of stream) {
-  if (chunk.type === "workflow-execution-suspended") {
-    console.log(chunk.payload.suspendPayload);
-    // { message: "Please confirm: delete old records", action: "delete old records" }
-  }
-}
-
-// User provides confirmation in their next message
-const resumedStream = await routingAgent.network("Yes, confirmed", {
-  autoResumeSuspendedTools: true,
-  memory: {
-    thread: "user-123",
-    resource: "my-app"
-  }
-});
-
-for await (const chunk of resumedStream) {
-  if (chunk.type === "network-execution-event-step-finish") {
-    console.log(chunk.payload.result);
-  }
-}
-```
-
-**Conversation flow:**
-
-```text
-User: "Delete the old records"
-Agent: "Please confirm: delete old records"
-
-User: "Yes, confirmed"
-Agent: "Records deleted successfully"
-```
-
-### Requirements
-
-For automatic tool resumption to work:
-
-- **Memory configured**: The agent needs memory to track suspended tools across messages
-- **Same thread**: The follow-up message must use the same memory thread and resource identifiers
-- **`resumeSchema` defined**: The tool (either directly in the network agent or in a subAgent) / workflow (step that gets suspended) must define a `resumeSchema` so the agent knows what data to extract from the user's message
-
-### Manual vs automatic resumption
-
-| Approach                               | Use case                                                                 |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| Manual (`resumeNetwork()`)             | Programmatic control, webhooks, button clicks, external triggers         |
-| Automatic (`autoResumeSuspendedTools`) | Conversational flows where users provide resume data in natural language |
-
-Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
-
-## Related
-
-- [Agent Networks](https://mastra.ai/docs/agents/networks)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
-- [Human-in-the-Loop](https://mastra.ai/docs/workflows/human-in-the-loop)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/docs-memory-storage.md

@@ -1,261 +0,0 @@
-# Storage
-
-For agents to remember previous interactions, Mastra needs a database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { LibSQLStore } from "@mastra/libsql";
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db",
-  }),
-});
-```
-
-> **Sharing the database with Mastra Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
->
-> ```typescript
-> url: "file:/absolute/path/to/your/project/mastra.db"
-> ```
->
-> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
-
-This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
-
-Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.
-
-## Supported providers
-
-Each provider page includes installation instructions, configuration parameters, and usage examples:
-
-- [libSQL](https://mastra.ai/reference/storage/libsql)
-- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
-- [MongoDB](https://mastra.ai/reference/storage/mongodb)
-- [Upstash](https://mastra.ai/reference/storage/upstash)
-- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
-- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
-- [Convex](https://mastra.ai/reference/storage/convex)
-- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
-- [LanceDB](https://mastra.ai/reference/storage/lance)
-- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
-
-> **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
-
-## Configuration scope
-
-Storage can be configured at the instance level (shared by all agents) or at the agent level (isolated to a specific agent).
-
-### Instance-level storage
-
-Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { PostgresStore } from "@mastra/pg";
-
-export const mastra = new Mastra({
-  storage: new PostgresStore({
-    id: 'mastra-storage',
-    connectionString: process.env.DATABASE_URL,
-  }),
-});
-
-// Both agents inherit storage from the Mastra instance above
-const agent1 = new Agent({ id: "agent-1", memory: new Memory() });
-const agent2 = new Agent({ id: "agent-2", memory: new Memory() });
-```
-
-This is useful when all primitives share the same storage backend and have similar performance, scaling, and operational requirements.
-
-#### Composite storage
-
-[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite) you need) to different storage providers.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { MastraCompositeStore } from "@mastra/core/storage";
-import { MemoryLibSQL } from "@mastra/libsql";
-import { WorkflowsPG } from "@mastra/pg";
-import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
-
-export const mastra = new Mastra({
-  storage: new MastraCompositeStore({
-    id: "composite",
-    domains: {
-      memory: new MemoryLibSQL({ url: "file:./memory.db" }),
-      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
-      observability: new ObservabilityStorageClickhouse({
-        url: process.env.CLICKHOUSE_URL,
-        username: process.env.CLICKHOUSE_USERNAME,
-        password: process.env.CLICKHOUSE_PASSWORD,
-      }),
-    },
-  }),
-});
-```
-
-This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
-
-### Agent-level storage
-
-Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data boundaries or compliance requirements:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { PostgresStore } from "@mastra/pg";
-
-export const agent = new Agent({
-  id: "agent",
-  memory: new Memory({
-    storage: new PostgresStore({
-      id: 'agent-storage',
-      connectionString: process.env.AGENT_DATABASE_URL,
-    }),
-  }),
-});
-```
-
-> **Warning:** [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment) doesn't support agent-level storage.
-
-## Threads and resources
-
-Mastra organizes conversations using two identifiers:
-
-- **Thread** - a conversation session containing a sequence of messages.
-- **Resource** - the entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
-
-Both identifiers are required for agents to store information:
-
-**Generate**:
-
-```typescript
-const response = await agent.generate("hello", {
-  memory: {
-    thread: "conversation-abc-123",
-    resource: "user_123",
-  },
-});
-```
-
-**Stream**:
-
-```typescript
-const stream = await agent.stream("hello", {
-  memory: {
-    thread: "conversation-abc-123",
-    resource: "user_123",
-  },
-});
-```
-
-> **Note:** [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
-
-### Thread title generation
-
-Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled.
-
-Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
-
-```typescript
-export const agent = new Agent({
-  id: "agent",
-  memory: new Memory({
-    options: {
-      generateTitle: true,
-    },
-  }),
-});
-```
-
-Title generation runs asynchronously after the agent responds and does not affect response time.
-
-To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
-
-```typescript
-export const agent = new Agent({
-  id: "agent",
-  memory: new Memory({
-    options: {
-      generateTitle: {
-        model: "openai/gpt-4o-mini",
-        instructions: "Generate a 1 word title",
-      },
-    },
-  }),
-});
-```
-
-## Semantic recall
-
-Semantic recall has different storage requirements - it needs a vector database in addition to the standard storage adapter. See [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) for setup and supported vector providers.
-
-## Handling large attachments
-
-Some storage providers enforce record size limits that base64-encoded file attachments (such as images) can exceed:
-
-| Provider                                                           | Record size limit |
-| ------------------------------------------------------------------ | ----------------- |
-| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
-| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
-| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
-
-PostgreSQL, MongoDB, and libSQL have higher limits and are generally unaffected.
-
-To avoid this, use an input processor to upload attachments to external storage (S3, R2, GCS, [Convex file storage](https://docs.convex.dev/file-storage), etc.) and replace them with URL references before persistence.
-
-```typescript
-import type { Processor } from "@mastra/core/processors";
-import type { MastraDBMessage } from "@mastra/core/memory";
-
-export class AttachmentUploader implements Processor {
-  id = "attachment-uploader";
-
-  async processInput({ messages }: { messages: MastraDBMessage[] }) {
-    return Promise.all(messages.map((msg) => this.processMessage(msg)));
-  }
-
-  async processMessage(msg: MastraDBMessage) {
-    const attachments = msg.content.experimental_attachments;
-    if (!attachments?.length) return msg;
-
-    const uploaded = await Promise.all(
-      attachments.map(async (att) => {
-        // Skip if already a URL
-        if (!att.url?.startsWith("data:")) return att;
-
-        // Upload base64 data and replace with URL
-        const url = await this.upload(att.url, att.contentType);
-        return { ...att, url };
-      })
-    );
-
-    return { ...msg, content: { ...msg.content, experimental_attachments: uploaded } };
-  }
-
-  async upload(dataUri: string, contentType?: string): Promise<string> {
-    const base64 = dataUri.split(",")[1];
-    const buffer = Buffer.from(base64, "base64");
-
-    // Replace with your storage provider (S3, R2, GCS, Convex, etc.)
-    // return await s3.upload(buffer, contentType);
-    throw new Error("Implement upload() with your storage provider");
-  }
-}
-```
-
-Use the processor with your agent:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { AttachmentUploader } from "./processors/attachment-uploader";
-
-const agent = new Agent({
-  id: "my-agent",
-  memory: new Memory({ storage: yourStorage }),
-  inputProcessors: [new AttachmentUploader()],
-});
-```

package/dist/docs/references/docs-observability-overview.md

@@ -1,70 +0,0 @@
-# Observability Overview
-
-Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.
-
-## Key Features
-
-### Tracing
-
-Specialized tracing for AI operations that captures:
-
-- **Model interactions**: Token usage, latency, prompts, and completions
-- **Agent execution**: Decision paths, tool calls, and memory operations
-- **Workflow steps**: Branching logic, parallel execution, and step outputs
-- **Automatic instrumentation**: Tracing with decorators
-
-## Storage Requirements
-
-The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default).
-
-For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
-
-## Quick Start
-
-Configure Observability in your Mastra instance:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/loggers";
-import { LibSQLStore } from "@mastra/libsql";
-import {
-  Observability,
-  DefaultExporter,
-  CloudExporter,
-  SensitiveDataFilter,
-} from "@mastra/observability";
-
-export const mastra = new Mastra({
-  logger: new PinoLogger(),
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db", // Storage is required for tracing
-  }),
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: "mastra",
-        exporters: [
-          new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
-        ],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
-        ],
-      },
-    },
-  }),
-});
-```
-
-> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete example.
-
-With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
-
-We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](https://mastra.ai/docs/observability/tracing/overview) documentation.
-
-## What's Next?
-
-- **[Set up Tracing](https://mastra.ai/docs/observability/tracing/overview)**: Configure tracing for your application
-- **[Configure Logging](https://mastra.ai/docs/observability/logging)**: Add structured logging
-- **[API Reference](https://mastra.ai/reference/observability/tracing/instances)**: Detailed configuration options