From 8214ebceaf9a2aedbb49c5ddc115bab214b7f855 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Sun, 15 Nov 2026 14:58:54 +0100 Subject: [PATCH] feat(plugins): append agent instructions on session open Recompute plugin instructions for each launch so changes apply on reopen without changing saved agent configuration. --- packages/plugin/src/server/lifecycle.ts | 2 + .../src/server/agent/agent-manager.test.ts | 66 +++++++++++++++++++ .../server/src/server/agent/agent-manager.ts | 10 +++ .../src/server/agent/agent-sdk-types.ts | 4 ++ .../src/server/agent/plugin-provider.ts | 9 ++- .../server/agent/providers/claude/agent.ts | 12 +++- .../agent/providers/codex-app-server-agent.ts | 4 ++ .../src/server/agent/providers/omp/agent.ts | 7 +- .../server/agent/providers/opencode-agent.ts | 2 + .../opencode/test-utils/v2-harness.ts | 13 +++- .../agent/providers/opencode/v2/agent.test.ts | 28 ++++++++ .../agent/providers/opencode/v2/session.ts | 9 ++- .../server/agent/providers/pi/agent.test.ts | 10 ++- .../src/server/agent/providers/pi/agent.ts | 9 +-- .../server/src/server/agent/system-prompt.ts | 12 ++++ .../src/server/plugins/lifecycle.e2e.test.ts | 39 ++++++++++- .../server/plugins/lifecycle/handlers.test.ts | 43 +++++++++++- .../src/server/plugins/lifecycle/index.ts | 15 ++++- .../agent-configuration/index.server.ts | 4 ++ public-docs/plugins/hooks.md | 47 ++++++++----- 20 files changed, 306 insertions(+), 39 deletions(-) diff --git a/packages/plugin/src/server/lifecycle.ts b/packages/plugin/src/server/lifecycle.ts index f1ee1a9790..cedc2e3019 100644 --- a/packages/plugin/src/server/lifecycle.ts +++ b/packages/plugin/src/server/lifecycle.ts @@ -88,6 +88,8 @@ export interface PluginSessionOpenRequest { readonly background: boolean; readonly labels: Readonly>; readonly metadata: Readonly>; + /** Instructions appended for this open; not saved on the agent. */ + appendSystemPrompt?: string[]; tools: AgentToolDefinition[]; env: Record; mcpServers: NonNullable; diff --git a/packages/server/src/server/agent/agent-manager.test.ts b/packages/server/src/server/agent/agent-manager.test.ts index 966b66f2ec..55027cf93a 100644 --- a/packages/server/src/server/agent/agent-manager.test.ts +++ b/packages/server/src/server/agent/agent-manager.test.ts @@ -14523,3 +14523,69 @@ test("idle cleanup gives a newly restored runtime a fresh idle window while keep expect((await h.sweep({ now: h.later(61) })).collected).toHaveLength(1); expect(h.closes).toBe(closesBeforeRestore + 1); }); + +test("plugin instructions are recomputed for each launch without changing saved config", async () => { + const workdir = mkdtempSync(join(tmpdir(), "agent-plugin-prompt-")); + const storage = new AgentStorage(join(workdir, "agents"), logger); + const client = new TestAgentClient(); + let additions = ["Plugin one", "Plugin two"]; + const manager = new AgentManager({ + clients: { codex: client }, + registry: storage, + logger, + appendSystemPrompt: "Daemon", + pluginLifecycle: { + emit: () => {}, + before: async (name, request) => + name === "agent.open.before" ? { ...request, appendSystemPrompt: additions } : request, + }, + }); + const snapshot = await manager.createAgent( + { provider: "codex", cwd: workdir, systemPrompt: "Saved" }, + undefined, + { workspaceId: undefined }, + ); + expect(client.createdConfigs[0]).toMatchObject({ + systemPrompt: "Saved", + daemonAppendSystemPrompt: "Daemon", + pluginAppendSystemPrompt: ["Plugin one", "Plugin two"], + }); + expect(snapshot.config.systemPrompt).toBe("Saved"); + expect((await storage.get(snapshot.id))?.config?.systemPrompt).toBe("Saved"); + const handle: AgentPersistenceHandle = { + provider: "codex", + sessionId: "prompt-session", + metadata: { provider: "codex", cwd: workdir, systemPrompt: "Saved" }, + }; + await manager.closeAgent(snapshot.id); + await manager.resumeAgentFromPersistence( + handle, + { cwd: workdir, systemPrompt: "Saved" }, + snapshot.id, + ); + expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual([ + "Plugin one", + "Plugin two", + ]); + additions = ["Changed"]; + await manager.closeAgent(snapshot.id); + await manager.resumeAgentFromPersistence( + handle, + { cwd: workdir, systemPrompt: "Saved" }, + snapshot.id, + ); + expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual(["Changed"]); + additions = ["Refreshed"]; + await manager.reloadAgentSession(snapshot.id); + expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual(["Refreshed"]); + additions = []; + await manager.closeAgent(snapshot.id); + await manager.resumeAgentFromPersistence( + handle, + { cwd: workdir, systemPrompt: "Saved" }, + snapshot.id, + ); + expect(client.resumeOverrides.at(-1)?.systemPrompt).toBe("Saved"); + expect(client.resumeOverrides.at(-1)?.daemonAppendSystemPrompt).toBe("Daemon"); + expect((await storage.get(snapshot.id))?.config?.systemPrompt).toBe("Saved"); +}); diff --git a/packages/server/src/server/agent/agent-manager.ts b/packages/server/src/server/agent/agent-manager.ts index 34af303027..414f4c016f 100644 --- a/packages/server/src/server/agent/agent-manager.ts +++ b/packages/server/src/server/agent/agent-manager.ts @@ -6168,6 +6168,7 @@ export class AgentManager { // A plugin changing during this open must still make the resulting session stale. const generation = this.sessionOpenGeneration; this.detachPluginTools(agentId); + let appendSystemPrompt: string[] | undefined; let mcpServers: AgentSessionConfig["mcpServers"]; let mcpServerOwners: Record | undefined; if (this.pluginLifecycle) { @@ -6189,12 +6190,14 @@ export class AgentManager { env = transformed.env; if (request.purpose === "interactive") { this.attachedPluginTools.set(agentId, transformed.tools as AttachedAgentTool[]); + appendSystemPrompt = transformed.appendSystemPrompt; mcpServers = transformed.mcpServers; mcpServerOwners = transformed.mcpServerOwners; } } const context: AgentLaunchContext = { agentId, + ...pluginPromptContext(appendSystemPrompt), mcpServers, mcpServerOwners, env: { @@ -6241,6 +6244,7 @@ export class AgentManager { throw new Error(`MCP server '${name}' from plugin ${owner} collides with ${existingOwner}`); } } + launchConfig = { ...launchConfig, pluginAppendSystemPrompt: launchContext.appendSystemPrompt }; const merged = Object.keys(launchContext.mcpServers ?? {}).length > 0 ? { @@ -6378,3 +6382,9 @@ export function commandMayHaveChangedExternalState(command: string): boolean { /\bgit\s+fetch\b/.test(normalized) ); } + +function pluginPromptContext( + appendSystemPrompt: string[] | undefined, +): Pick { + return appendSystemPrompt?.length ? { appendSystemPrompt } : {}; +} diff --git a/packages/server/src/server/agent/agent-sdk-types.ts b/packages/server/src/server/agent/agent-sdk-types.ts index 0267876d0d..53130191b3 100644 --- a/packages/server/src/server/agent/agent-sdk-types.ts +++ b/packages/server/src/server/agent/agent-sdk-types.ts @@ -621,6 +621,8 @@ export interface AgentSessionConfig { * persisted into agent config so daemon setting changes apply cleanly. */ daemonAppendSystemPrompt?: string; + /** Plugin instructions for this launch; never persisted. */ + pluginAppendSystemPrompt?: string[]; modeId?: string; model?: string; thinkingOptionId?: string; @@ -636,6 +638,8 @@ export interface AgentSessionConfig { } export interface AgentLaunchContext { + /** Launch-only instructions contributed by plugins. */ + appendSystemPrompt?: string[]; /** Launch-only plugin MCP servers and their owners; never persisted. */ mcpServers?: Record; mcpServerOwners?: Record; diff --git a/packages/server/src/server/agent/plugin-provider.ts b/packages/server/src/server/agent/plugin-provider.ts index 480d9deec7..3b64f7c9f9 100644 --- a/packages/server/src/server/agent/plugin-provider.ts +++ b/packages/server/src/server/agent/plugin-provider.ts @@ -1949,7 +1949,11 @@ function mapSessionConfig( return { cwd: config.cwd, env: createProviderEnv({ baseEnv: {}, overlays: [launchContext?.env] }), - systemPrompt: combineSystemPrompts(config.systemPrompt, config.daemonAppendSystemPrompt), + systemPrompt: combineSystemPrompts( + config.systemPrompt, + config.daemonAppendSystemPrompt, + ...(config.pluginAppendSystemPrompt ?? []), + ), mcpServers: { ...config.mcpServers }, toolPolicy: config.toolPolicy ? { preapproved: config.toolPolicy.preapproved.map((grant) => ({ ...grant })) } @@ -1968,8 +1972,9 @@ function mapSessionConfig( function combineSystemPrompts( systemPrompt: string | undefined, daemonPrompt: string | undefined, + ...pluginPrompts: string[] ): string | undefined { - const parts = [systemPrompt, daemonPrompt].filter( + const parts = [systemPrompt, daemonPrompt, ...pluginPrompts].filter( (value): value is string => typeof value === "string" && value.trim().length > 0, ); return parts.length > 0 ? parts.join("\n\n") : undefined; diff --git a/packages/server/src/server/agent/providers/claude/agent.ts b/packages/server/src/server/agent/providers/claude/agent.ts index 8bafb4e1e1..c33a2e6593 100644 --- a/packages/server/src/server/agent/providers/claude/agent.ts +++ b/packages/server/src/server/agent/providers/claude/agent.ts @@ -3044,7 +3044,11 @@ class ClaudeAgentSession implements AgentSession { if (!this.claudeSessionId) { return null; } - const { providerOptions: _providerOptions, ...persistedConfig } = this.config; + const { + providerOptions: _providerOptions, + pluginAppendSystemPrompt: _pluginAppendSystemPrompt, + ...persistedConfig + } = this.config; this.persistence = { provider: "claude", sessionId: this.claudeSessionId, @@ -3712,7 +3716,11 @@ class ClaudeAgentSession implements AgentSession { private buildAppendedSystemPrompt(): string { return ( - composeSystemPromptParts(this.config.systemPrompt, this.config.daemonAppendSystemPrompt) ?? "" + composeSystemPromptParts( + this.config.systemPrompt, + this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), + ) ?? "" ); } diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.ts index bb7faab9e0..fb29c0e9ac 100644 --- a/packages/server/src/server/agent/providers/codex-app-server-agent.ts +++ b/packages/server/src/server/agent/providers/codex-app-server-agent.ts @@ -4047,6 +4047,7 @@ export class CodexAppServerAgentSession implements AgentSession { match.developer_instructions, this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); if (developerInstructions) settings.developer_instructions = developerInstructions; if (this.config.model) settings.model = this.config.model; @@ -4311,6 +4312,7 @@ export class CodexAppServerAgentSession implements AgentSession { const developerInstructions = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); if (developerInstructions) { params.developerInstructions = developerInstructions; @@ -4464,6 +4466,7 @@ export class CodexAppServerAgentSession implements AgentSession { const developerInstructions = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); if (developerInstructions) { params.developerInstructions = developerInstructions; @@ -5806,6 +5809,7 @@ export class CodexAppServerAgentSession implements AgentSession { const developerInstructions = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); const params: Record = { model, diff --git a/packages/server/src/server/agent/providers/omp/agent.ts b/packages/server/src/server/agent/providers/omp/agent.ts index d10692ca6f..9a2e426c3c 100644 --- a/packages/server/src/server/agent/providers/omp/agent.ts +++ b/packages/server/src/server/agent/providers/omp/agent.ts @@ -466,6 +466,7 @@ function buildResumeStartInput(input: { systemPrompt: composeSystemPromptParts( input.resumeConfig.config.systemPrompt, input.resumeConfig.config.daemonAppendSystemPrompt, + ...(input.resumeConfig.config.pluginAppendSystemPrompt ?? []), ), }; } @@ -2370,7 +2371,11 @@ export class OmpAgentClient implements AgentClient { noSession: config.internal === true, modeId: launchMode.modeId, extraArgs: launchMode.extraArgs, - systemPrompt: composeSystemPromptParts(config.systemPrompt, config.daemonAppendSystemPrompt), + systemPrompt: composeSystemPromptParts( + config.systemPrompt, + config.daemonAppendSystemPrompt, + ...(config.pluginAppendSystemPrompt ?? []), + ), env: launchContext?.env, }; const runtimeSession = await this.resolveRuntime(config.providerOptions).startSession( diff --git a/packages/server/src/server/agent/providers/opencode-agent.ts b/packages/server/src/server/agent/providers/opencode-agent.ts index 85c32e978f..950d7d9e90 100644 --- a/packages/server/src/server/agent/providers/opencode-agent.ts +++ b/packages/server/src/server/agent/providers/opencode-agent.ts @@ -3692,6 +3692,7 @@ class OpenCodeAgentSession implements AgentSession { const systemPrompt = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); const model = this.parseModel(this.config.model); const effectiveMode = resolveOpenCodeRuntimeAgentId(this.currentMode); @@ -4029,6 +4030,7 @@ class OpenCodeAgentSession implements AgentSession { const systemPrompt = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); const promptResponse = await this.client.session.promptAsync({ sessionID: this.sessionId, diff --git a/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts b/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts index 66ee191707..46ec3d7d15 100644 --- a/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts +++ b/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts @@ -28,6 +28,7 @@ export class V2Harness { readonly prompts: string[] = []; readonly environments: Array<{ sessionID: string; variables: Record }> = []; readonly mcpAdds: string[] = []; + readonly instructions = new Map(); releases = 0; active = false; activeReads = 0; @@ -153,7 +154,17 @@ export class V2Harness { environment: async (input) => { this.environments.push(input); }, - instructions: { entry: { list: unexpected, put: unexpected, remove: unexpected } }, + instructions: { + entry: { + list: async () => [...this.instructions].map(([key, value]) => ({ key, value })), + put: async ({ key, value }) => { + this.instructions.set(key, String(value)); + }, + remove: async ({ key }) => { + this.instructions.delete(key); + }, + }, + }, prompt: async (input, options) => { const before = this.executions.length; await this.prompt(input, options); diff --git a/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts b/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts index 58e9ffaefb..e657aba7bc 100644 --- a/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts +++ b/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts @@ -17,6 +17,34 @@ function terminalEvents(events: AgentStreamEvent[]) { } describe("OpenCode v2 session lifecycle", () => { + test("reopening replaces and removes plugin instructions", async () => { + const harness = new V2Harness(); + const client = new OpenCodeV2AgentClient({ + logger: createTestLogger(), + runtime: harness.runtime, + }); + const created = await client.createSession({ + provider: "opencode", + cwd: "/tmp/project", + pluginAppendSystemPrompt: ["first"], + }); + expect(harness.instructions.get("paseo")).toBe("first"); + const handle = created.describePersistence()!; + await created.close(); + const resumed = await client.resumeSession(handle, { + cwd: "/tmp/project", + pluginAppendSystemPrompt: ["changed"], + }); + expect(harness.instructions.get("paseo")).toBe("changed"); + await resumed.close(); + const cleared = await client.resumeSession(handle, { + cwd: "/tmp/project", + pluginAppendSystemPrompt: undefined, + }); + expect(harness.instructions.has("paseo")).toBe(false); + await cleared.close(); + }); + test("refreshes the existing location before reading a forced catalog", async () => { const harness = new V2Harness(); const refreshed: string[] = []; diff --git a/packages/server/src/server/agent/providers/opencode/v2/session.ts b/packages/server/src/server/agent/providers/opencode/v2/session.ts index 1724bacbe7..bfba0afff1 100644 --- a/packages/server/src/server/agent/providers/opencode/v2/session.ts +++ b/packages/server/src/server/agent/providers/opencode/v2/session.ts @@ -196,13 +196,20 @@ export class OpenCodeV2Session implements AgentSession { const system = composeSystemPromptParts( this.config.systemPrompt, this.config.daemonAppendSystemPrompt, + ...(this.config.pluginAppendSystemPrompt ?? []), ); - if (system) + if (system) { await this.client.session.instructions.entry.put({ sessionID: this.id, key: "paseo", value: system, }); + } else { + const entries = await this.client.session.instructions.entry.list({ sessionID: this.id }); + if (entries.some((entry) => entry.key === "paseo")) { + await this.client.session.instructions.entry.remove({ sessionID: this.id, key: "paseo" }); + } + } } private async startStream() { let ready!: () => void; diff --git a/packages/server/src/server/agent/providers/pi/agent.test.ts b/packages/server/src/server/agent/providers/pi/agent.test.ts index d152810a92..abe1447e68 100644 --- a/packages/server/src/server/agent/providers/pi/agent.test.ts +++ b/packages/server/src/server/agent/providers/pi/agent.test.ts @@ -1892,6 +1892,7 @@ describe("PiRpcAgentSession", () => { createConfig({ systemPrompt: "Agent prompt", daemonAppendSystemPrompt: "Daemon prompt", + pluginAppendSystemPrompt: ["Plugin one", "Plugin two"], }), ); @@ -1910,7 +1911,9 @@ describe("PiRpcAgentSession", () => { await expect( applyPaseoExtensionSystemPrompt(actualLaunch.extensionPaths[0]!, "Pi project prompt"), - ).resolves.toBe("Pi project prompt\n\nAgent prompt\n\nDaemon prompt"); + ).resolves.toBe( + "Pi project prompt\n\nAgent prompt\n\nDaemon prompt\n\nPlugin one\n\nPlugin two", + ); await session.close(); }); @@ -1933,6 +1936,7 @@ describe("PiRpcAgentSession", () => { }, { daemonAppendSystemPrompt: "Daemon prompt", + pluginAppendSystemPrompt: ["Plugin one", "Plugin two"], }, ); @@ -1956,7 +1960,9 @@ describe("PiRpcAgentSession", () => { ]); await expect( applyPaseoExtensionSystemPrompt(actualLaunch.extensionPaths[0]!, "Pi project prompt"), - ).resolves.toBe("Pi project prompt\n\nAgent prompt\n\nDaemon prompt"); + ).resolves.toBe( + "Pi project prompt\n\nAgent prompt\n\nDaemon prompt\n\nPlugin one\n\nPlugin two", + ); }); test("updates model and thinking through Pi runtime commands", async () => { diff --git a/packages/server/src/server/agent/providers/pi/agent.ts b/packages/server/src/server/agent/providers/pi/agent.ts index 60d745ea24..db2cef229a 100644 --- a/packages/server/src/server/agent/providers/pi/agent.ts +++ b/packages/server/src/server/agent/providers/pi/agent.ts @@ -52,7 +52,7 @@ import { type ResolvedProviderLaunch, } from "../../provider-launch-config.js"; import { renderPromptAttachmentAsText } from "../../prompt-attachments.js"; -import { composeSystemPromptParts } from "../../system-prompt.js"; +import { composeAgentSystemPrompt } from "../../system-prompt.js"; import { buildBinaryDiagnosticRows, buildCommandResolutionDiagnosticRows, @@ -2630,7 +2630,7 @@ export class PiRpcAgentClient implements AgentClient { const mcp = await this.prepareMcpInjection(config.cwd, config.mcpServers, mcpEnv, runtime); const mcpConfigFile = mcp?.kind === "adapter" ? mcp.configFile : null; const paseoExtension = createPiPaseoExtensionFile({ - systemPrompt: composeSystemPromptParts(config.systemPrompt, config.daemonAppendSystemPrompt), + systemPrompt: composeAgentSystemPrompt(config), mcpServers: mcp?.kind === "builtin" ? mcp.servers : undefined, }); let runtimeSession: PiRuntimeSession; @@ -2699,10 +2699,7 @@ export class PiRpcAgentClient implements AgentClient { ); const mcpConfigFile = mcp?.kind === "adapter" ? mcp.configFile : null; const paseoExtension = createPiPaseoExtensionFile({ - systemPrompt: composeSystemPromptParts( - resumeConfig.config.systemPrompt, - resumeConfig.config.daemonAppendSystemPrompt, - ), + systemPrompt: composeAgentSystemPrompt(resumeConfig.config), mcpServers: mcp?.kind === "builtin" ? mcp.servers : undefined, }); const tempFiles = mcpConfigFile ? [mcpConfigFile, paseoExtension] : [paseoExtension]; diff --git a/packages/server/src/server/agent/system-prompt.ts b/packages/server/src/server/agent/system-prompt.ts index 2aafc3759b..5dff1e6602 100644 --- a/packages/server/src/server/agent/system-prompt.ts +++ b/packages/server/src/server/agent/system-prompt.ts @@ -8,3 +8,15 @@ export function composeSystemPromptParts( return prompt.length > 0 ? prompt : undefined; } + +export function composeAgentSystemPrompt(config: { + systemPrompt?: string; + daemonAppendSystemPrompt?: string; + pluginAppendSystemPrompt?: string[]; +}): string | undefined { + return composeSystemPromptParts( + config.systemPrompt, + config.daemonAppendSystemPrompt, + ...(config.pluginAppendSystemPrompt ?? []), + ); +} diff --git a/packages/server/src/server/plugins/lifecycle.e2e.test.ts b/packages/server/src/server/plugins/lifecycle.e2e.test.ts index d08089ad3d..aab2a9bd15 100644 --- a/packages/server/src/server/plugins/lifecycle.e2e.test.ts +++ b/packages/server/src/server/plugins/lifecycle.e2e.test.ts @@ -527,13 +527,25 @@ test("agent creation hooks change the provider and environment before the sessio }); server.addHook("agent.open.before", async ({ request }) => { console.log(JSON.stringify({ hook: "agent.open.before", request })); - return { ...request, env: { ...request.env, HOOK_OPEN: "opened" } }; + return { ...request, appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "Plugin instructions"], env: { ...request.env, HOOK_OPEN: "opened" } }; }); server.addHook("agent.create.after", async (event) => { console.log(JSON.stringify({ hook: "agent.create.after", event })); });`, reportOpen: true, }); + const extraPlugin = path.join(directory, "extra-plugin"); + await mkdir(extraPlugin); + await writeFile( + path.join(extraPlugin, "paseo-plugin.json"), + JSON.stringify({ id: "a-prompt", requirements: { paseo: ">=0.8.0" } }), + ); + const writePrompt = (prompt: string) => + writeFile( + path.join(extraPlugin, "index.server.ts"), + `export default function contribute(server) { server.addHook("agent.open.before", async ({ request }) => ({ ...request, appendSystemPrompt: [...(request.appendSystemPrompt ?? []), ${JSON.stringify(prompt)}] })); return () => {}; }`, + ); + await writePrompt("First plugin"); const daemon = await createTestPaseoDaemon(); const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); try { @@ -541,15 +553,17 @@ test("agent creation hooks change the provider and environment before the sessio await client.fetchAgents({ subscribe: {} }); await client.patchDaemonConfig({ pluginsEnabled: true }); await client.installDirectoryPlugin(pluginDirectory); + await client.installDirectoryPlugin(extraPlugin); const agent = await client.createAgent({ provider: "claude", cwd: directory, title: "Hook test", + systemPrompt: "Saved instructions", }); expect(agent.provider).toBe(PROVIDER_ID); expect(await daemon.daemon.agentStorage.get(agent.id)).toMatchObject({ provider: PROVIDER_ID, - config: { model: "shutdown-model" }, + config: { model: "shutdown-model", systemPrompt: "Saved instructions" }, }); await expect .poll(async () => { @@ -569,13 +583,32 @@ test("agent creation hooks change the provider and environment before the sessio }, { hook: "provider.open", - config: { env: { HOOK_CREATE: "created", HOOK_OPEN: "opened" } }, + config: { + env: { HOOK_CREATE: "created", HOOK_OPEN: "opened" }, + systemPrompt: "Saved instructions\n\nFirst plugin\n\nPlugin instructions", + }, }, { hook: "agent.create.after", event: { agent: { id: agent.id, provider: PROVIDER_ID } }, }, ]); + await writePrompt("Changed plugin"); + await client.reloadPlugin("a-prompt"); + await daemon.daemon.agentManager.reloadAgentSession(agent.id); + await client.disablePlugin("a-prompt"); + await daemon.daemon.agentManager.reloadAgentSession(agent.id); + const opens = (await client.getPluginLogs("shutdown-provider-plugin")) + .filter((entry) => entry.message.startsWith('{"hook":"provider.open"')) + .map((entry) => JSON.parse(entry.message).config.systemPrompt); + expect(opens).toEqual([ + "Saved instructions\n\nFirst plugin\n\nPlugin instructions", + "Saved instructions\n\nChanged plugin\n\nPlugin instructions", + "Saved instructions\n\nPlugin instructions", + ]); + expect((await daemon.daemon.agentStorage.get(agent.id))?.config?.systemPrompt).toBe( + "Saved instructions", + ); await client.archiveAgent(agent.id); } finally { await client.close(); diff --git a/packages/server/src/server/plugins/lifecycle/handlers.test.ts b/packages/server/src/server/plugins/lifecycle/handlers.test.ts index bf7526ba1d..6ff3361f22 100644 --- a/packages/server/src/server/plugins/lifecycle/handlers.test.ts +++ b/packages/server/src/server/plugins/lifecycle/handlers.test.ts @@ -228,7 +228,9 @@ test.each([{ title: "Changed" }, { labels: { changed: "true" } }, { background: }, paseo, ), - ).rejects.toThrow("agent.open.before hooks can only change env, tools, and mcpServers"); + ).rejects.toThrow( + "agent.open.before hooks can only change env, tools, mcpServers, and appendSystemPrompt", + ); }, ); @@ -357,3 +359,42 @@ test("checkout-branch hooks reject a branch-off baseRef", async () => { validateBeforeResult("worktree.create.before", request, { ...request, baseRef: "main" }), ).rejects.toThrow(/baseRef/); }); + +test("session-open instructions compose, survive old hooks, and are ignored for history", async () => { + const hooks = new PluginHookHandlers(() => {}); + hooks.addHook("agent.open.before", async ({ request }) => ({ + ...request, + appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "first"], + })); + hooks.addHook("agent.open.before", async ({ request }) => { + const { appendSystemPrompt: _ignored, ...oldRequest } = request; + return oldRequest; + }); + hooks.addHook("agent.open.before", async ({ request }) => ({ + ...request, + appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "second"], + })); + const input = { + agentId: "agent", + workspaceId: null, + provider: "codex", + cwd: "/project", + reason: "resume", + purpose: "interactive", + env: {}, + title: null, + labels: {}, + metadata: {}, + tools: [], + mcpServers: {}, + }; + const interactive = await hooks.invoke("interactive", "agent.open.before", input, paseo); + expect(interactive).toMatchObject({ appendSystemPrompt: ["first", "second"] }); + const history = await hooks.invoke( + "history", + "agent.open.before", + { ...input, purpose: "history" }, + paseo, + ); + expect(history).not.toHaveProperty("appendSystemPrompt"); +}); diff --git a/packages/server/src/server/plugins/lifecycle/index.ts b/packages/server/src/server/plugins/lifecycle/index.ts index b291bf3723..46e2a87d66 100644 --- a/packages/server/src/server/plugins/lifecycle/index.ts +++ b/packages/server/src/server/plugins/lifecycle/index.ts @@ -108,6 +108,7 @@ const beforeSchemas = { labels: z.record(z.string(), z.string()), // Optional so a plugin that returns its own object keeps working; omitted means unchanged. metadata: z.record(z.string(), z.custom()).optional(), + appendSystemPrompt: z.array(z.string()).optional(), tools: z.array(agentToolMetadataSchema), env: z.record(z.string(), z.string()), mcpServers: CreateAgentRequestMessageSchema.shape.config.shape.mcpServers.unwrap(), @@ -248,9 +249,18 @@ export async function validateBeforeResult { ## agent.open.before -Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open. +Receives `{ request }`; only `env`, `appendSystemPrompt`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open. Do not await a write to the agent being opened: `setMetadata`, `setLabels`, or an option, model, thinking or mode change. The write waits for the open to finish, the open waits for your hook, so the hook times out and the open fails. Start the write without awaiting it; it runs right after the open: @@ -329,6 +329,17 @@ server.addHook("agent.open.before", async ({ request }, { paseo }) => { | `purpose` | `interactive`, `history` | | `env` | Launch override map; excludes the daemon's inherited environment. Replace the map to add, replace, or remove overrides. | +### Append instructions on every session opening + +```ts +server.addHook("agent.open.before", async ({ request }) => ({ + ...request, + appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "Follow the team engineering guide."], +})); +``` + +Instructions follow the saved agent prompt and daemon instructions, in plugin order. They are not saved in the agent configuration and are ignored for history opens. Reload the plugin after changing its data to apply new instructions on the next reopen. Running turns continue; removing an instruction does not remove conversation history. The ACP adapter does not send system instructions to its providers. Plugin providers receive the composed prompt, but must apply it themselves. + ### Inject environment variables on every session opening ```ts