From ec08b05da109180f7012c085d57d361929390281 Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Thu, 2 Apr 2026 16:34:57 +0800
Subject: [PATCH] feat(ext): add `systemInstruction` to ExecuteConfig

Expose a serializable `systemInstruction` string field on the
page-facing ExecuteConfig, mapped to `instructions.system` when
creating MultiPageAgent. Functions cannot cross the postMessage
boundary, so this flat string field replaces the object form.

Closes #359
---
 packages/extension/docs/extension_api.md                   | 7 +++++++
 packages/extension/src/entrypoints/content.ts              | 6 +++++-
 packages/extension/src/entrypoints/main-world.ts           | 7 +++++++
 .../src/pages/docs/features/chrome-extension/page.tsx      | 1 +
 4 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/extension/docs/extension_api.md b/packages/extension/docs/extension_api.md
index d7dc902..1586660 100644
--- a/packages/extension/docs/extension_api.md
+++ b/packages/extension/docs/extension_api.md
@@ -118,6 +118,10 @@ export interface ExecuteConfig {
   model: string
   apiKey?: string
 
+  // Global system-level instructions for the agent.
+  // Equivalent to AgentConfig.instructions.system.
+  systemInstruction?: string
+
   // Include the initial tab where page JS starts. Default: true.
   includeInitialTab?: boolean
 
@@ -212,6 +216,9 @@ interface ExecuteConfig {
   baseURL: string
   model: string
   apiKey?: string
+
+  systemInstruction?: string
+
   includeInitialTab?: boolean
   experimentalIncludeAllTabs?: boolean
   onStatusChange?: (status: AgentStatus) => void
diff --git a/packages/extension/src/entrypoints/content.ts b/packages/extension/src/entrypoints/content.ts
index e06dd1f..1bcfc8a 100644
--- a/packages/extension/src/entrypoints/content.ts
+++ b/packages/extension/src/entrypoints/content.ts
@@ -70,11 +70,15 @@ async function exposeAgentToPage() {
 
 				try {
 					const { task, config } = payload
+					const { systemInstruction, ...agentConfig } = config
 
 					// Dispose old instance before creating new one
 					multiPageAgent?.dispose()
 
-					multiPageAgent = new MultiPageAgent(config)
+					multiPageAgent = new MultiPageAgent({
+						...agentConfig,
+						instructions: systemInstruction ? { system: systemInstruction } : undefined,
+					})
 
 					// events
 
diff --git a/packages/extension/src/entrypoints/main-world.ts b/packages/extension/src/entrypoints/main-world.ts
index c7946e8..b401beb 100644
--- a/packages/extension/src/entrypoints/main-world.ts
+++ b/packages/extension/src/entrypoints/main-world.ts
@@ -7,6 +7,12 @@ export interface ExecuteConfig {
 	model: string
 	apiKey?: string
 
+	/**
+	 * Global system-level instructions for the agent.
+	 * Equivalent to `AgentConfig.instructions.system`.
+	 */
+	systemInstruction?: string
+
 	/**
 	 * Whether to include the initial tab (that holds this main world script) in the task.
 	 * @default true
@@ -89,6 +95,7 @@ export default defineUnlistedScript(() => {
 						baseURL: config.baseURL,
 						model: config.model,
 						apiKey: config.apiKey,
+						systemInstruction: config.systemInstruction,
 						includeInitialTab: config.includeInitialTab,
 						experimentalIncludeAllTabs: config.experimentalIncludeAllTabs,
 					},
diff --git a/packages/website/src/pages/docs/features/chrome-extension/page.tsx b/packages/website/src/pages/docs/features/chrome-extension/page.tsx
index acee2a6..8ae0ea2 100644
--- a/packages/website/src/pages/docs/features/chrome-extension/page.tsx
+++ b/packages/website/src/pages/docs/features/chrome-extension/page.tsx
@@ -199,6 +199,7 @@ interface ExecuteConfig {
 	model: string     // Model name
 	apiKey?: string   // LLM AK
 
+	systemInstruction?: string // Global system-level instructions
 	includeInitialTab?: boolean
 	experimentalIncludeAllTabs?: boolean // Control all unpinned tabs in the window
 	onStatusChange?: (status: AgentStatus) => void