AIPex Documentation

Plugins allow you to observe and customize runtime behavior using hooks. You can implement an AgentPlugin to:

• Mutate input before a turn (beforeChat)
• Observe tool lifecycle events (onToolEvent)
• Observe per-turn usage metrics (onMetrics)
• Observe the final response (afterResponse)

import { google } from "@ai-sdk/google";
import { AIPex, aisdk, type AgentPlugin } from "@aipexstudio/aipex-core";

const loggerPlugin: AgentPlugin = {
  id: "logger",
  hooks: {
    beforeChat: (payload) => {
      console.log("[beforeChat]", payload.input);
      return payload;
    },
    onToolEvent: ({ event }) => {
      if (event.type === "tool_call_start") {
        console.log("[tool]", event.toolName, event.params);
      }
    },
  },
};

const agent = AIPex.create({
  instructions: "You are a helpful assistant.",
  model: aisdk(google("gemini-2.5-flash")),
  plugins: [loggerPlugin],
});

AIPex follows a strict multi-package (monorepo) architecture to prevent platform coupling and circular dependencies. When developing or extending the project, you must adhere to these dependency rules:

• @core: The foundation. Contains pure TypeScript interface definitions, types, and abstract classes. It must have zero dependencies on any other package or platform API.
• @browser-runtime: The Chrome implementation. It implements the interfaces defined in @core using CDP (Chrome DevTools Protocol) and contains runtime logic. It may only depend on @core.
• @aipex-react: The UI layer. Contains pure UI components, Hooks, and adapters. It may only depend on @core. Strictly prohibited: @aipex-react must never depend on @browser-runtime to avoid platform coupling.
• @use-cases: The application layer. Contains workflow templates and use-case implementations. It is allowed to depend on all lower-level packages.
• browser-ext: The extension entry point. This is the final assembly point where all packages are composed and environment configurations are applied.

┌─────────────────────────────────────────────────────┐
│                     @core                           │
│            (纯 TypeScript 接口定义)                  │
│    - 无平台依赖                                      │
│    - 仅类型、接口、抽象类                            │
└──────────────┬──────────────────┬───────────────────┘
               │                  │
       ┌───────┴────────┐  ┌─────┴──────────┐
       │                │  │                 │
       ▼                │  ▼                 │
┌─────────────────┐     │  ┌─────────────────┐
│ @browser-runtime│     │  │  @aipex-react   │
│ (Chrome 实现)   │     │  │  (React UI)     │
│ - CDP 集成      │     │  │  - 纯 UI 组件   │
│ - 工具实现      │     │  │  - Hooks        │
│ - 运行时逻辑    │     │  │  - 适配器       │
└────────┬────────┘     │  └────────┬────────┘
         │              │           │
         └──────────────┼───────────┘
                        │
                        ▼
               ┌─────────────────┐
               │   @use-cases    │
               │ (应用层，新建)   │
               │ - 工作流模板     │
               │ - 用例实现       │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │   browser-ext   │
               │   (扩展入口)     │
               │ - 最终组装       │
               │ - 环境配置       │
               └─────────────────┘

AIPex implements different trust levels for various entry points to the sidepanel. When integrating or extending the sidepanel, follow these security models:

Entry Point Trust Levels

• Trusted (User-triggered): chrome.action.onClicked and chrome.commands (shortcuts) require no additional validation.
• Semi-trusted (Content Script): Messages from content scripts via open-sidepanel are handled by the Background script using sidePanel.open. To maintain security, the Background script does not pass data directly through this call.
• External (External Sources): Messages received via onMessageExternal (e.g., openWithPrompt) must be restricted using the externally_connectable key in manifest.json.

Message Validation Requirements

• openWithPrompt: The prompt must be a non-empty string. Data is passed via chrome.storage.local rather than direct UI injection. The sidepanel must validate the timestamp to ensure it is within a 5-second TTL (Time-To-Live).
• REPLAY_USER_MANUAL: When implementing this external message, you must perform schema validation on the steps array to prevent the injection of malicious step data.
• Custom Model Hosts: When using BYOK (Bring Your Own Key) with a custom aiHost URL, ensure the URL is validated to prevent SSRF (Server-Side Request Forgery) attacks.