### Local Development Setup (Bash)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Provides a sequence of bash commands for setting up and running the project locally. Includes installing dependencies, building native modules, starting Docker services, running database migrations, and starting development servers.

```bash
# Install dependencies
yarn install

# Build native Rust modules
yarn oa @afk/server-native build

# Start Docker services (PostgreSQL + Redis)
docker compose -f .docker/dev/compose.yml up -d

# Run database migrations
cd packages/backend/server
yarn prisma migrate dev

# Start development servers
yarn dev  # Runs web (port 8080) + server (port 3010)
```

--------------------------------

### Start Backend Dependencies with Docker Compose

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Starts the backend services using Docker Compose. Requires copying an example compose file to `docker-compose.yml` if it doesn't exist. This command brings up essential backend infrastructure like databases.

```bash
docker compose -f ./.docker/dev/compose.yml up
```

--------------------------------

### Install Project Dependencies with Yarn

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Installs all project dependencies using Yarn. This is a foundational step for setting up the development environment.

```bash
yarn
```

--------------------------------

### Start Local Development Server (Monorepo)

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Starts both the web application and the backend server simultaneously from the monorepo root. This is the primary command for local development.

```bash
yarn dev
```

--------------------------------

### Example Local Development .env Configuration

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Provides example environment variable settings for local development. Users should replace placeholder values with their actual secrets and credentials for databases, authentication, mailers, and API keys.

```dotenv
# Example .env values for local development.
# Replace placeholder values with your own secrets as needed.

# Database connection string
DATABASE_URL="postgresql://open-agent:open-agent@localhost:5432/open-agent"

# Auth and web URLs
NEXTAUTH_URL="http://localhost:8080"

# Mailer configuration
MAILER_SENDER="noreply@example.com"
MAILER_USER="your_mail_user"
MAILER_PASSWORD="your_mail_password"
MAILER_HOST="localhost"
MAILER_PORT="1025"

# Stripe API keys (use your own test keys)
STRIPE_API_KEY=sk_test_your_stripe_api_key
STRIPE_WEBHOOK_KEY=whsec_your_stripe_webhook_key

# OAuth credentials (replace with your own)
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

# Copilot/AI API keys (replace with your own)
COPILOT_OPENAI_API_KEY=your_openai_api_key
COPILOT_PERPLEXITY_API_KEY=your_perplexity_api_key
COPILOT_FAL_API_KEY=your_fal_api_key
COPILOT_GOOGLE_API_KEY=your_google_api_key
```

--------------------------------

### Start Local Backend Development Server

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Starts only the backend server development. This command is useful for back-end focused development and typically listens on port 3010.

```bash
yarn dev:server
```

--------------------------------

### Start Local Web Development Server

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Starts only the web application development server, typically running on port 8080. This command is useful for front-end focused development.

```bash
yarn dev:web
```

--------------------------------

### Build Rust Native Bindings

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Builds the Rust native bindings for the project. This command should be run once after initial setup or when native code changes.

```bash
yarn oa @afk/server-native build
```

--------------------------------

### Basic Extension Provider Setup with Zod

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Defines a custom basic extension provider by extending `BaseExtensionProvider`. It uses Zod for schema validation of provider options and includes custom setup logic within the `setup` method.

```typescript
import { BaseExtensionProvider } from '@blocksuite/affine-ext-loader';
import { z } from 'zod';

// Create a custom provider with options
class MyProvider extends BaseExtensionProvider<'my-scope', { enabled: boolean }> {
  name = 'MyProvider';

  schema = z.object({
    enabled: z.boolean(),
  });

  setup(context: Context<'my-scope'>, options?: { enabled: boolean }) {
    super.setup(context, options);
    // Custom setup logic
  }
}
```

--------------------------------

### Run Database Migrations with Prisma

Source: https://github.com/afk-surf/open-agent/blob/master/tools/public/dev.md

Executes database migrations using Prisma. This command is typically run from the `packages/backend/server/` directory and is optional, used for managing database schema changes.

```bash
(cd packages/backend/server && yarn prisma migrate dev)
```

--------------------------------

### Configuration Management

Source: https://context7.com/afk-surf/open-agent/llms.txt

Information on how to configure the Open Agent, including Docker deployment, configuration file structure, environment variables, and local development setup.

```APIDOC
## Configuration Management

### Docker Deployment

#### Description
Steps to deploy the Open Agent using Docker, including copying configuration files, editing API keys, and starting services.

#### Commands
```bash
# Copy configuration files
mkdir deploy && cd deploy
cp ../.docker/config.example.json ./config.json
cp ../.docker/docker-compose.yml ./docker-compose.yml

# Edit config.json with your API keys
nano config.json

# Start services
docker compose up -d
```

### Configuration File (`config.json`)

#### Description
Structure of the main configuration file, detailing settings for AI providers, storage, and OAuth.

#### File Format
```json
{
  "copilot": {
    "enabled": true,
    "providers.openai": {
      "apiKey": "sk-..."
    },
    "providers.anthropic": {
      "apiKey": "sk-ant-..."
    },
    "providers.gemini": {
      "apiKey": "..."
    },
    "providers.perplexity": {
      "apiKey": "..."
    },
    "providers.fal": {
      "apiKey": "..."
    },
    "exa": {
      "key": "..."
    },
    "e2b": {
      "key": "..."
    },
    "browserUse": {
      "key": "..."
    },
    "storage": {
      "provider": "cloudflare-r2",
      "bucket": "my-bucket",
      "config": {
        "accountId": "...",
        "credentials": {
          "accessKeyId": "...",
          "secretAccessKey": "..."
        }
      }
    }
  },
  "oauth": {
    "providers.github": {
      "clientId": "...",
      "clientSecret": "..."
    },
    "providers.google": {
      "clientId": "...",
      "clientSecret": "..."
    }
  }
}
```

### Environment Variables

#### Description
Alternative configuration options using environment variables for database, Redis, AI providers, storage, and server settings.

#### Variables
- `DATABASE_URL` (string) - PostgreSQL connection URL.
- `REDIS_SERVER_HOST` (string) - Redis server host.
- `REDIS_SERVER_PORT` (number) - Redis server port.
- `COPILOT_OPENAI_API_KEY` (string) - OpenAI API key.
- `COPILOT_ANTHROPIC_API_KEY` (string) - Anthropic API key.
- `COPILOT_GEMINI_API_KEY` (string) - Gemini API key.
- `COPILOT_STORAGE_PROVIDER` (string) - Storage provider (e.g., 'cloudflare-r2').
- `COPILOT_STORAGE_BUCKET` (string) - Storage bucket name.
- `NODE_ENV` (string) - Node environment (e.g., 'production').
- `SERVER_PORT` (number) - Server port.

#### Example Usage (Bash)
```bash
# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/open_agent"

# Redis
REDIS_SERVER_HOST="localhost"
REDIS_SERVER_PORT=6379

# AI Providers (alternative to config.json)
COPILOT_OPENAI_API_KEY="sk-..."
COPILOT_ANTHROPIC_API_KEY="sk-ant-..."
COPILOT_GEMINI_API_KEY="..."

# Storage
COPILOT_STORAGE_PROVIDER="cloudflare-r2"
COPILOT_STORAGE_BUCKET="my-bucket"

# Server
NODE_ENV="production"
SERVER_PORT=3010
```

### Local Development

#### Description
Instructions for setting up and running the Open Agent in a local development environment.

#### Commands
```bash
# Install dependencies
yarn install

# Build native Rust modules
yarn oa @afk/server-native build

# Start Docker services (PostgreSQL + Redis)
docker compose -f .docker/dev/compose.yml up -d

# Run database migrations
cd packages/backend/server
yarn prisma migrate dev

# Start development servers
yarn dev  # Runs web (port 8080) + server (port 3010)
```
```

--------------------------------

### Workflow Execution Overview (JavaScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Provides a high-level overview of the workflow execution process, detailing the sequence of events from node start to node end, including text deltas and attachments. This is an illustrative example.

```javascript
// Workflow automatically:
// 1. Generates outline (chat_text node)
// 2. Creates slides content (chat_text node)
// 3. Generates images for slides (chat_image node)
// 4. Assembles final presentation

// Events received:
// node_start -> text-delta -> node_end -> node_start -> attachment -> ...
```

--------------------------------

### Docker Deployment Configuration (Bash)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Provides bash commands for setting up a Dockerized environment for deployment. This includes copying configuration files, editing the `config.json`, and starting the services using `docker compose`.

```bash
# Copy configuration files
mkdir deploy && cd deploy
cp ../.docker/config.example.json ./config.json
cp ../.docker/docker-compose.yml ./docker-compose.yml

# Edit config.json with your API keys
nano config.json

# Start services
docker compose up -d
```

--------------------------------

### Run Development Commands Defined in package.json

Source: https://github.com/afk-surf/open-agent/blob/master/tools/cli/README.md

Starts development servers or watchers for specified packages, as defined in their package.json scripts. For example, running the 'dev' script for the 'web' package.

```bash
yarn oa web dev
# or
yarn dev -p i18n
```

--------------------------------

### Store Extension Provider and Manager Configuration

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Implements a `StoreExtensionProvider` with a schema for `cacheSize` and registers extensions in its setup. It also demonstrates creating and configuring a `StoreExtensionManager`.

```typescript
import { StoreExtensionProvider, StoreExtensionManager } from '@blocksuite/affine-ext-loader';
import { z } from 'zod';

// Create a store provider with custom options
class MyStoreProvider extends StoreExtensionProvider<{ cacheSize: number }> {
  override name = 'MyStoreProvider';

  override schema = z.object({
    cacheSize: z.number().min(0),
  });

  override setup(context: StoreExtensionContext, options?: { cacheSize: number }) {
    super.setup(context, options);
    context.register([Ext1, Ext2, Ext3]);
  }
}

// Create and use the store extension manager
const manager = new StoreExtensionManager([MyStoreProvider]);
manager.configure(MyStoreProvider, { cacheSize: 100 });
const extensions = manager.get('store');
```

--------------------------------

### Manage Multiple Chat Session Stores (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Illustrates how to manage multiple chat sessions using a central store. Covers creating new sessions, getting or creating existing ones, removing sessions, and listing all active sessions.

```typescript
import { chatSessionsStore } from '@afk/app/store/copilot/sessions-store';

// Create new session
const sessionId = await chatSessionsStore.getState().createSession('chat', {
  pinned: true
});

// Get or create session store
const sessionStore = chatSessionsStore.getState().getOrCreateSession(sessionId);

// Remove session
await chatSessionsStore.getState().removeSession(sessionId);

// List all active sessions
const allSessions = chatSessionsStore.getState().sessions;
```

--------------------------------

### IPC Communication from Renderer Process

Source: https://github.com/afk-surf/open-agent/blob/master/packages/frontend/electron/src/entries/main/state/README.md

Provides examples of how to interact with the state management system from an Electron renderer process using `ipcRenderer`. It shows how to invoke IPC handlers to get state, update state, and trigger an immediate save (`flush`). It also demonstrates listening for state change events.

```typescript
// In renderer process
import { ipcRenderer } from 'electron';

// Get state
const state = await ipcRenderer.invoke('getState');

// Update state
await ipcRenderer.invoke('updateState', {
  userPreferences: {
    recentFiles: ['file1.txt', 'file2.txt'],
  },
});

// Listen to state changesipcRenderer.on('state', (_, state) => {
  console.log('State updated:', state);
});

// Force immediate save from renderer
await ipcRenderer.invoke('flushState');

```

--------------------------------

### Creating Standalone State Service

Source: https://github.com/afk-surf/open-agent/blob/master/packages/frontend/electron/src/entries/main/state/README.md

Shows how to create a standalone `JsonStateService` outside of a framework like NestJS. This example demonstrates direct instantiation of the factory with a file path, initial state, schema, and custom options for faster saving and state update hooks.

```typescript
import { createJsonStateService } from './json-state.factory';

// Create a standalone service (not NestJS)
const myState = createJsonStateService('/absolute/path/to/my-state.json', { count: 0, name: 'test' }, type({ count: 'number', name: 'string' }), {
  saveDebounceMs: 500, // Faster saves
  beforeStateUpdate: state => ({ ...state, updatedAt: Date.now() }),
});

// Use it directly
await myState.updateState({ count: 1 });
const current = myState.getState();
await myState.flush();
myState.destroy(); // Cleanup when done

```

--------------------------------

### Using affine-template in Test Cases

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/shared/src/test-utils/README.md

Shows a practical example of integrating affine-template.ts within a test suite (using vitest) to generate documents for validation. It demonstrates creating a document, extracting blocks by flavour, and asserting their counts.

```typescript
import { describe, expect, it } from 'vitest';
import { affine } from '../__tests__/utils/affine-template';

describe('My Test', () => {
  it('should correctly handle document structure', () => {
    const doc = affine`
      <affine-page>
        <affine-note>
          <affine-paragraph>Test content</affine-paragraph>
        </affine-note>
      </affine-page>
    `;

    // Get blocks
    const pages = doc.getBlocksByFlavour('affine:page');
    const notes = doc.getBlocksByFlavour('affine:note');
    const paragraphs = doc.getBlocksByFlavour('affine:paragraph');

    expect(pages.length).toBe(1);
    expect(notes.length).toBe(1);
    expect(paragraphs.length).toBe(1);

    // Perform more tests here...
  });
});
```

--------------------------------

### Deploy Open-Agent with Docker Compose

Source: https://github.com/afk-surf/open-agent/blob/master/README.md

This snippet demonstrates the steps to deploy Open-Agent using Docker Compose. It involves copying configuration and Docker Compose files, editing the configuration with API keys, and starting the services.

```sh
mkdir deploy
cd deploy
cp ../.docker/config.example.json ./config.json
cp ../.docker/docker-compose.yml ./docker-compose.yml
docker compose up -d
```

--------------------------------

### Generate Images with Model Override and Retry (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript example shows how to make an API request to generate images, with options to specify a model ID and enable retries. It uses the Fetch API and demonstrates processing the response body as a stream.

```typescript
// With model override and retry
fetch(`/api/copilot/chat/${sessionId}/images?retry=true&modelId=fal-ai/flux-pro`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(async response => {
  const reader = response.body.getReader();
  // Process SSE stream
});
```

--------------------------------

### Stream Copilot Responses (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript example shows how to consume streaming responses from the Copilot client. It utilizes an async iterator to process chunks of the response, parsing 'text-delta', 'tool-call', and 'tool-result' events to update the UI or perform actions.

```typescript
// Stream with automatic parsing
const stream = copilotClient.chatTextStream({
  sessionId: sessionId,
  reasoning: true,
  webSearch: false,
  tools: ['pythonSandbox', 'webSearch'],
  modelId: 'gpt-4o',
  signal: abortController.signal
}, 'stream-object');

for await (const chunk of stream) {
  if (chunk.type === 'text-delta') {
    updateUI(chunk.textDelta);
  } else if (chunk.type === 'tool-call') {
    console.log(`Calling ${chunk.toolName} with`, chunk.args);
  } else if (chunk.type === 'tool-result') {
    console.log('Tool result:', chunk.result);
  }
}
```

--------------------------------

### Send Messages to Copilot (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript code demonstrates sending various types of messages using the Copilot Client SDK. It includes examples for plain text messages with optional parameters, messages with file attachments, and messages containing image data.

```typescript
// Text message
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'Explain quantum computing',
  params: { temperature: 0.7 }
});

// With file attachments
const files = [document.getElementById('file1').files[0]];
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'Summarize these documents',
  blobs: files
});

// Image input
const imageBlob = await fetch('/path/to/image.png').then(r => r.blob());
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'What is in this image?',
  blob: imageBlob
});
```

--------------------------------

### Enable Tools in Session (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Demonstrates how to create a new AI session and enable specific tools for use within that session. Tools include web search, Python sandbox, browser automation, and document interaction.

```typescript
const sessionId = await copilotClient.createSession({
  promptName: 'chat',
  tools: [
    'webSearch',
    'pythonSandbox',
    'browserUse',
    'makeItReal',
    'docRead',
    'docEdit',
    'codeArtifact'
  ]
});
```

--------------------------------

### Execute Presentation Workflow (GraphQL & Bash)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Shows how to trigger a presentation generation workflow using a GraphQL mutation or a REST API call. The workflow includes multiple steps handled automatically by the system.

```graphql
mutation GeneratePresentation($sessionId: String!, $messageId: String!) {
  # Workflow endpoint automatically handles multi-step generation
}
```

```bash
# Execute via REST
curl -N "http://localhost:3010/api/copilot/chat/{sessionId}/workflow?messageId=msg-id" \
  -H "Authorization: Bearer token"
```

--------------------------------

### Extension Configuration Methods

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Demonstrates how to configure extensions using the `configure` method of an extension manager. This includes setting configuration directly, updating it using a function that receives the previous configuration, and removing configuration.

```typescript
// Set configuration directly
manager.configure(MyProvider, { enabled: true });

// Update configuration using a function
manager.configure(MyProvider, prev => {
  if (!prev) return prev;
  return {
    ...prev,
    enabled: !prev.enabled,
  };
});

// Remove configuration
manager.configure(MyProvider, undefined);
```

--------------------------------

### Frontend Client SDK

Source: https://context7.com/afk-surf/open-agent/llms.txt

Documentation for the Frontend Client SDK, covering initialization, session management, message sending, streaming responses, and context management.

```APIDOC
## Frontend Client SDK

### Initialize Client

Initializes the CopilotClient with necessary dependencies like a GraphQL client and event source factory.

```typescript
import { CopilotClient } from '@afk/app/store/copilot/client';
import { createGraphQLClient } from '@afk/graphql';

const gqlClient = createGraphQLClient('http://localhost:3010/graphql', {
  getAuthToken: () => localStorage.getItem('token')
});

const copilotClient = new CopilotClient(
  gqlClient.query,
  fetch,
  (url, init) => new EventSource(url, init)
);
```

### Session Management

APIs for creating, updating, retrieving, and listing chat sessions.

```typescript
// Create new session
const sessionId = await copilotClient.createSession({
  promptName: 'chat',
  pinned: true,
  reuseLatestChat: false
});

// Update session metadata
await copilotClient.updateSession({
  sessionId,
  pinned: false,
  metadata: JSON.stringify({ customField: 'value' })
});

// Get session details
const session = await copilotClient.getSession(sessionId);
console.log(session.model, session.createdAt);

// List all sessions
const { edges, pageInfo } = await copilotClient.getSessions(
  { first: 20, after: null },
  { pinned: true }
);
```

### Send Messages

APIs for sending different types of messages, including text, files, and images.

```typescript
// Text message
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'Explain quantum computing',
  params: { temperature: 0.7 }
});

// With file attachments
const files = [document.getElementById('file1').files[0]];
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'Summarize these documents',
  blobs: files
});

// Image input
const imageBlob = await fetch('/path/to/image.png').then(r => r.blob());
await copilotClient.createMessage({
  sessionId: sessionId,
  content: 'What is in this image?',
  blob: imageBlob
});
```

### Streaming Responses

Handles streaming responses from the chat, parsing different event types like text deltas, tool calls, and tool results.

```typescript
// Stream with automatic parsing
const stream = copilotClient.chatTextStream({
  sessionId: sessionId,
  reasoning: true,
  webSearch: false,
  tools: ['pythonSandbox', 'webSearch'],
  modelId: 'gpt-4o',
  signal: abortController.signal
}, 'stream-object');

for await (const chunk of stream) {
  if (chunk.type === 'text-delta') {
    updateUI(chunk.textDelta);
  } else if (chunk.type === 'tool-call') {
    console.log(`Calling ${chunk.toolName} with`, chunk.args);
  } else if (chunk.type === 'tool-result') {
    console.log('Tool result:', chunk.result);
  }
}
```

### Context Management

APIs for managing context for Retrieval Augmented Generation (RAG), including adding and listing documents, chat history, and files.

```typescript
// Create context for RAG
const contextId = await copilotClient.createContext(sessionId);

// Add PDF document
const pdfFile = new File([pdfBlob], 'research.pdf');
await copilotClient.addContextFile(pdfFile, contextId);

// Add workspace document
await copilotClient.addContextDoc(contextId, 'workspace-doc-uuid');

// Add chat history from another session
await copilotClient.addContextChat(contextId, 'other-session-id');

// List context items
const contexts = await copilotClient.listContext(sessionId);
contexts.forEach(item => {
  console.log(item.type, item.name);
});

// Remove context item
await copilotClient.removeContextFile(contextId, 'file-uuid');
```
```

--------------------------------

### Show CLI Help Information

Source: https://github.com/afk-surf/open-agent/blob/master/tools/cli/README.md

Displays the help menu for the Open-Agent CLI, outlining available commands and options. This is useful for understanding the CLI's capabilities and syntax.

```bash
yarn oa -h
```

--------------------------------

### Initialize Copilot Client (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript code initializes the CopilotClient, a crucial part of the Frontend Client SDK. It demonstrates creating a GraphQL client and then instantiating the CopilotClient by providing dependencies for GraphQL queries, fetch requests, and Server-Sent Events (SSE) connections.

```typescript
import { CopilotClient } from '@afk/app/store/copilot/client';
import { createGraphQLClient } from '@afk/graphql';

const gqlClient = createGraphQLClient('http://localhost:3010/graphql', {
  getAuthToken: () => localStorage.getItem('token')
});

const copilotClient = new CopilotClient(
  gqlClient.query,
  fetch,
  (url, init) => new EventSource(url, init)
);
```

--------------------------------

### Configuration File Structure (JSON)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Illustrates the structure of the `config.json` file, detailing settings for Copilot providers (OpenAI, Anthropic, Gemini, etc.), storage (Cloudflare R2), and OAuth providers (GitHub, Google).

```json
{
  "copilot": {
    "enabled": true,
    "providers.openai": {
      "apiKey": "sk-…"
    },
    "providers.anthropic": {
      "apiKey": "sk-ant-…"
    },
    "providers.gemini": {
      "apiKey": "…"
    },
    "providers.perplexity": {
      "apiKey": "…"
    },
    "providers.fal": {
      "apiKey": "…"
    },
    "exa": {
      "key": "…"
    },
    "e2b": {
      "key": "…"
    },
    "browserUse": {
      "key": "…"
    },
    "storage": {
      "provider": "cloudflare-r2",
      "bucket": "my-bucket",
      "config": {
        "accountId": "…",
        "credentials": {
          "accessKeyId": "…",
          "secretAccessKey": "…"
        }
      }
    }
  },
  "oauth": {
    "providers.github": {
      "clientId": "…",
      "clientSecret": "…"
    },
    "providers.google": {
      "clientId": "…",
      "clientSecret": "…"
    }
  }
}
```

--------------------------------

### One-time Initialization using 'effect' in View Extensions

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Illustrates the use of the `effect` method within a `ViewExtensionProvider` for one-time initialization tasks such as setting up global state, registering Lit elements, and configuring event listeners. This method ensures that initialization logic runs only once per provider class.

```typescript
class MyViewProvider extends ViewExtensionProvider {
  override effect() {
    // This will only run once, even if multiple instances are created
    initializeGlobalState();
    registerLitElements();
    setupGlobalEventListeners();
  }
}
```

--------------------------------

### JavaScript: Mocking Browser Plugins

Source: https://github.com/afk-surf/open-agent/blob/master/packages/common/native/fixtures/sample.html

This function mocks the browser's navigator.plugins property. It can be configured to block access, provide an empty string, or trigger a placeholder element. This is useful for preventing fingerprinting via browser plugins.

```javascript
function processFunctions(scope) {
    /* Browser Plugins */
    if (browserplugins == 'true') {
        scope.Object.defineProperty(navigator, 'plugins', {
            enumerable: true,
            configurable: true,
            get: function () {
                var browserplugins_triggerblock = scope.document.createElement('div');
                browserplugins_triggerblock.className = 'scriptsafe_oiigbmnaadbkfbmpbfijlflahbdbdgdf_browserplugins';
                browserplugins_triggerblock.title = 'navigator.plugins';
                document.documentElement.appendChild(browserplugins_triggerblock);
                return '';
            },
        });
    }
```

--------------------------------

### Initialize Open-Agent Monorepo Structure

Source: https://github.com/afk-surf/open-agent/blob/master/tools/cli/README.md

Generates essential files and configurations required for the Open-Agent monorepo to function correctly. This command does not include per-project codegen.

```bash
yarn oa init
```

--------------------------------

### Create Complex Document Structure with affine-template

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/shared/src/test-utils/README.md

Illustrates how to construct more complex AFFiNE documents using affine-template.ts, including multiple notes and paragraphs within a single page. This example shows how to define page titles and nested block structures.

```typescript
// Create a document with multiple notes and paragraphs
const doc = affine`
  <affine-page title="My Test Page">
    <affine-note>
      <affine-paragraph>First paragraph</affine-paragraph>
      <affine-paragraph>Second paragraph</affine-paragraph>
    </affine-note>
    <affine-note>
      <affine-paragraph>Another note</affine-paragraph>
    </affine-note>
  </affine-page>
`;
```

--------------------------------

### Usage of Built-in State Service

Source: https://github.com/afk-surf/open-agent/blob/master/packages/frontend/electron/src/entries/main/state/README.md

Illustrates how to use a pre-configured `StateService` within a NestJS application. It covers getting the current state, subscribing to state changes using RxJS observables, updating the state with debounced saving, and forcing an immediate save.

```typescript
import { StateService } from './state';

// Inject in your service
constructor(private stateService: StateService) {}

// Get current state
const currentState = this.stateService.getState();

// Subscribe to state changes
this.stateService.getState$().subscribe(state => {
  console.log('State updated:', state);
});

// Update state (debounced save)
await this.stateService.updateState({
  settings: {
    theme: 'dark',
    autoSave: false,
  },
});

// Force immediate save
await this.stateService.flush();

```

--------------------------------

### Manage Chat Session Store (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Demonstrates how to create, interact with, and manage a single chat session store. Includes subscribing to state, sending messages with attachments and reasoning, regenerating responses, stopping generation, and using a React hook for integration.

```typescript
import { createChatSessionStore } from '@afk/app/store/copilot/session-store';

const sessionStore = createChatSessionStore(sessionId, copilotClient);

// Subscribe to state
const { messages, isLoading, isStreaming } = sessionStore.getState();

// Send message with automatic streaming
await sessionStore.getState().sendMessage({
  content: 'Hello',
  attachments: [file1, file2]
}, {
  reasoning: true,
  tools: ['webSearch', 'pythonSandbox']
});

// Regenerate last response
await sessionStore.getState().regenerate();

// Regenerate from specific message
await sessionStore.getState().regenerate('message-uuid');

// Stop ongoing generation
sessionStore.getState().stopGeneration();

// React hook usage
function ChatComponent() {
  const messages = sessionStore(state => state.messages);
  const sendMessage = sessionStore(state => state.sendMessage);

  return (
    <div>
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
      <button onClick={() => sendMessage({ content: 'Hi' })}>
        Send
      </button>
    </div>
  );
}
```

--------------------------------

### Stream Text Response - REST API

Source: https://context7.com/afk-surf/open-agent/llms.txt

Enables streaming of text responses from the AI via Server-Sent Events (SSE). The endpoint provides real-time updates on message deltas, tool calls, tool results, and completion status. Includes `curl` example and frontend consumption logic.

```bash
curl -N "http://localhost:3010/api/copilot/chat/{sessionId}/stream-object?messageId=msg-id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```javascript
// Server-Sent Events response
event: message
data: {"type":"text-delta","textDelta":"Hello"}

event: message
data: {"type":"tool-call","toolName":"webSearch","args":{"query":"OpenAI API"}}

event: message
data: {"type":"tool-result","toolCallId":"1","result":"Found 10 results"}

event: message
data: {"type":"finish","finishReason":"stop","usage":{"promptTokens":100,"completionTokens":50}}
```

```typescript
// Frontend consumption
const eventSource = new EventSource(
  `/api/copilot/chat/${sessionId}/stream-object`,
  { headers: { Authorization: `Bearer ${token}` } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'text-delta') {
    appendText(data.textDelta);
  } else if (data.type === 'tool-call') {
    displayToolCall(data.toolName, data.args);
  }
};
```

--------------------------------

### Environment Variables Configuration (Bash)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Lists essential environment variables for configuring the application, including database connection, Redis server details, AI provider API keys, storage settings, and server parameters.

```bash
# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/open_agent"

# Redis
REDIS_SERVER_HOST="localhost"
REDIS_SERVER_PORT=6379

# AI Providers (alternative to config.json)
COPILOT_OPENAI_API_KEY="sk-…"
COPILOT_ANTHROPIC_API_KEY="sk-ant-…"
COPILOT_GEMINI_API_KEY="…"

# Storage
COPILOT_STORAGE_PROVIDER="cloudflare-r2"
COPILOT_STORAGE_BUCKET="my-bucket"

# Server
NODE_ENV="production"
SERVER_PORT=3010
```

--------------------------------

### Manage Context Files Listing

Source: https://github.com/afk-surf/open-agent/blob/master/packages/backend/server/src/__tests__/__snapshots__/copilot.e2e.ts.md

Demonstrates how context files are managed and listed. This includes file details such as blob ID, chunk size, name, and processing status.

```typescript
[
  {
    blobId: 'Ip3vuwzubwJnOlzeKQ0Gc-daDcMc7EOYnIqypOyn4bs',
    chunkSize: 0,
    name: 'sample.pdf',
    status: 'processing',
  },
]
```

--------------------------------

### List Available AI Providers (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Displays a configuration object showing the AI providers that can be used, such as Anthropic, OpenAI, Gemini, Perplexity, and Fal. It lists the models available under each provider.

```typescript
// Configured in config.json
const providers = {
  'anthropic': {
    models: ['claude-3-opus', 'claude-3-sonnet', 'claude-3-haiku']
  },
  'openai': {
    models: ['gpt-4o', 'gpt-4-turbo', 'o1', 'dall-e-3']
  },
  'gemini': {
    models: ['gemini-1.5-pro', 'gemini-1.5-flash']
  },
  'perplexity': {
    models: ['sonar-reasoning', 'sonar']
  },
  'fal': {
    models: ['fal-ai/flux-pro', 'fal-ai/flux-dev', 'fal-ai/stable-diffusion-v3']
  }
};
```

--------------------------------

### Create Basic Document with affine-template

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/shared/src/test-utils/README.md

Demonstrates the basic usage of the affine-template.ts utility to create a simple AFFiNE document with a single paragraph. It requires importing the 'affine' function from '@blocksuite/affine-shared/test-utils'.

```typescript
import { affine } from '@blocksuite/affine-shared/test-utils';

// Create a simple document
const doc = affine`
  <affine-page>
    <affine-note>
      <affine-paragraph>Hello, World!</affine-paragraph>
    </affine-note>
  </affine-page>
`;
```

--------------------------------

### Dependency Injection with Extension Managers

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Shows how to access extension managers, such as `ViewExtensionManager`, through the dependency injection container using `std.get`. This allows for retrieving specific extensions based on their scope.

```typescript
// Access the manager through the di container
const viewManager = std.get(ViewExtensionManagerIdentifier);
const pagePreviewExtension = viewManager.get('preview-page');
```

--------------------------------

### Manage Copilot Sessions (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript snippet illustrates session management within the Copilot Client SDK. It covers creating a new session with specific parameters, updating existing session metadata, retrieving detailed session information, and listing multiple sessions with filtering capabilities.

```typescript
// Create new session
const sessionId = await copilotClient.createSession({
  promptName: 'chat',
  pinned: true,
  reuseLatestChat: false
});

// Update session metadata
await copilotClient.updateSession({
  sessionId,
  pinned: false,
  metadata: JSON.stringify({ customField: 'value' })
});

// Get session details
const session = await copilotClient.getSession(sessionId);
console.log(session.model, session.createdAt);

// List all sessions
const { edges, pageInfo } = await copilotClient.getSessions(
  { first: 20, after: null },
  { pinned: true }
);
```

--------------------------------

### Manage Context for RAG (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

This TypeScript code illustrates context management for Retrieval Augmented Generation (RAG) using the Copilot Client SDK. It covers creating a context, adding various sources like PDF documents, workspace documents, and chat history from other sessions, listing context items, and removing them.

```typescript
// Create context for RAG
const contextId = await copilotClient.createContext(sessionId);

// Add PDF document
const pdfFile = new File([pdfBlob], 'research.pdf');
await copilotClient.addContextFile(pdfFile, contextId);

// Add workspace document
await copilotClient.addContextDoc(contextId, 'workspace-doc-uuid');

// Add chat history from another session
await copilotClient.addContextChat(contextId, 'other-session-id');

// List context items
const contexts = await copilotClient.listContext(sessionId);
contexts.forEach(item => {
  console.log(item.type, item.name);
});

// Remove context item
await copilotClient.removeContextFile(contextId, 'file-uuid');
```

--------------------------------

### Handle Missing Doc: Return Null with Error Details (JSON)

Source: https://github.com/afk-surf/open-agent/blob/master/packages/backend/server/src/__tests__/e2e/doc-service/__snapshots__/controller.spec.ts.md

This snippet demonstrates the JSON response when documentation is not found. It includes fields like 'code', 'message', 'name', 'status', and 'type' to clearly indicate the error condition.

```json
{
  "code": "Not Found",
  "message": "Doc not found",
  "name": "NOT_FOUND",
  "status": 404,
  "type": "RESOURCE_NOT_FOUND"
}
```

--------------------------------

### View Extension Provider and Manager with Scopes

Source: https://github.com/afk-surf/open-agent/blob/master/blocksuite/affine/ext-loader/README.md

Defines a `ViewExtensionProvider` with a `theme` schema and conditional registration of extensions based on view scope and options. It shows creating and configuring a `ViewExtensionManager` and retrieving extensions for different scopes.

```typescript
import { ViewExtensionProvider, ViewExtensionManager } from '@blocksuite/affine-ext-loader';
import { z } from 'zod';

// Create a view provider with custom options
class MyViewProvider extends ViewExtensionProvider<{ theme: string }> {
  override name = 'MyViewProvider';

  override schema = z.object({
    theme: z.enum(['light', 'dark']),
  });

  override setup(context: ViewExtensionContext, options?: { theme: string }) {
    super.setup(context, options);

    context.register([CommonExt]);
    if (context.scope === 'page') {
      context.register([PageExt]);
    } else if (context.scope === 'edgeless') {
      context.register([EdgelessExt]);
    }
    if (options?.theme === 'dark') {
      context.register([DarkModeExt]);
    }
  }

  // Override effect to run one-time initialization logic
  override effect() {
    // This will only run once per provider class
    console.log('Initializing MyViewProvider');
    // Register lit elements
    this.registerLitElements();
  }
}

// Create and use the view extension manager
const manager = new ViewExtensionManager([MyViewProvider]);
manager.configure(MyViewProvider, { theme: 'dark' });

// Get extensions for different view scopes
const pageExtensions = manager.get('page');
const edgelessExtensions = manager.get('edgeless');
```

--------------------------------

### Create Custom State Service with Factory

Source: https://github.com/afk-surf/open-agent/blob/master/packages/frontend/electron/src/entries/main/state/README.md

Demonstrates creating a custom, type-safe state service using the `createJsonStateService` factory. It includes schema definition, service instantiation with options like custom debounce time and before-state-update hooks, and lifecycle management for NestJS applications.

```typescript
import { Injectable, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
import { type } from 'arktype';
import { createJsonStateService, JsonStateService } from './json-state.factory';

// Define your schema
const MyStateSchema = type({
  property1: 'string',
  property2: 'number',
  lastModified: 'number',
});

type MyState = typeof MyStateSchema.infer;

@Injectable()
export class MyStateService implements OnModuleInit, OnApplicationShutdown {
  private stateService: JsonStateService<MyState>;

  constructor() {
    this.stateService = createJsonStateService(
      'my-state.json', // filepath (relative to userData or absolute)
      defaultMyState,
      MyStateSchema,
      {
        // Optional hooks
        beforeStateUpdate: state => ({ ...state, lastModified: Date.now() }),
        saveDebounceMs: 2000, // Custom debounce time
      }
    );
  }

  async onModuleInit() {
    // Factory handles initialization automatically
  }

  async onApplicationShutdown() {
    await this.stateService.flush();
    this.stateService.destroy();
  }

  // Delegate methods
  getState() {
    return this.stateService.getState();
  }
  async updateState(update: Partial<MyState>) {
    return this.stateService.updateState(update);
  }
}

```

--------------------------------

### Render Test Email HTML

Source: https://github.com/afk-surf/open-agent/blob/master/packages/backend/server/src/__tests__/__snapshots__/mails.spec.ts.md

This snippet shows the HTML structure for a basic test email from Open-Agent. It includes a main heading and a body paragraph, styled for readability. No external dependencies are required for rendering this HTML.

```html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--$-->
<table
  align="center"
  width="100%"
  border="0"
  cellpadding="0"
  cellspacing="0"
  role="presentation">
  <tbody>
    <tr>
      <td>
        <p
          style="font-size:20px;line-height:28px;font-weight:600;font-family:Inter, Arial, Helvetica, sans-serif;margin-top:24px;margin-bottom:0;color:#141414">
          Test Email from Open-Agent
        </p>
      </td>
    </tr>
  </tbody>
</table>
<table
  align="center"
  width="100%"
  border="0"
  cellpadding="0"
  cellspacing="0"
  role="presentation">
  <tbody>
    <tr>
      <td>
        <p
          style="font-size:15px;line-height:24px;font-weight:400;font-family:Inter, Arial, Helvetica, sans-serif;margin-top:24px;margin-bottom:0;color:#141414">
          This is a test email from your Open-Agent instance.
        </p>
      </td>
    </tr>
  </tbody>
</table>
<!--/$-->
```

--------------------------------

### GraphQL API - RAG and Context Management

Source: https://context7.com/afk-surf/open-agent/llms.txt

APIs for creating and managing Retrieval-Augmented Generation (RAG) contexts, including adding documents and chat history.

```APIDOC
## GraphQL API - RAG and Context Management

### Create RAG Context

#### Description
Initializes a new RAG context for a given session.

### Method
Mutation

### Endpoint
`/graphql`

### Parameters
#### Request Body (Mutation)
- **createCopilotContext** (object) - Options for creating the context.
  - **sessionId** (String!) - The ID of the session to associate the context with.

### Response
#### Success Response (200)
- **createCopilotContext** (String) - The ID of the created context.

---

### Add Document to Context

#### Description
Adds a document file to a RAG context.

### Method
Mutation

### Endpoint
`/graphql`

### Parameters
#### Request Body (Mutation)
- **addContextFile** (object) - Options for adding a file.
  - **contextId** (String!) - The ID of the context to add the file to.
  - **content** (Upload!) - The file content to upload.

### Response
#### Success Response (200)
- **addContextFile** (Boolean) - Indicates if the file was added successfully.

---

### Add Chat History to Context

#### Description
Adds the history of a chat session to a RAG context.

### Method
Mutation

### Endpoint
`/graphql`

### Parameters
#### Request Body (Mutation)
- **addContextChat** (object) - Options for adding chat history.
  - **contextId** (String!) - The ID of the context to add the chat history to.
  - **sessionId** (String!) - The ID of the chat session whose history to add.

### Response
#### Success Response (200)
- **addContextChat** (Boolean) - Indicates if the chat history was added successfully.

#### Complete RAG Flow Example
```javascript
// Assuming createContext, addContextFile, addContextDoc are defined elsewhere
const contextId = await createContext(sessionId);
await addContextFile(contextId, pdfFile);
await addContextDoc(contextId, 'workspace-doc-id');
// Context automatically used in subsequent messages with semantic search
```
```

--------------------------------

### Handle Tool Responses (TypeScript)

Source: https://context7.com/afk-surf/open-agent/llms.txt

Illustrates how to stream responses from the AI, handling different event types such as tool calls, tool results, and text deltas. This is crucial for managing the AI's interaction with tools.

```typescript
const stream = copilotClient.chatTextStream({
  sessionId,
  tools: ['webSearch', 'pythonSandbox']
}, 'stream-object');

for await (const event of stream) {
  switch (event.type) {
    case 'tool-call':
      console.log(`Calling: ${event.toolName}`);
      console.log('Arguments:', event.args);
      break;
    case 'tool-result':
      console.log(`Result from ${event.toolName}:`, event.result);
      break;
    case 'text-delta':
      process.stdout.write(event.textDelta);
      break;
  }
}
```