Skip to content

Commit 51f78d6

Browse files
feat: Support custom instructions for agent sessions via meta (#546)
1 parent 51aa211 commit 51f78d6

39 files changed

Lines changed: 108 additions & 34 deletions

‎src/AirExtension.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ export const AIR_EXTENSION_CAPABILITIES_KEY = "capabilities";
1515
export const AIR_DIFF_PATCH_KEY = "diffPatch";
1616
export const AIR_SESSION_FAILURE_KEY = "sessionFailure";
1717
export const AIR_AGENT_FILE_CHANGE_REPORT_KEY = "agentFileChangeReport";
18+
export const AIR_CUSTOM_INSTRUCTIONS_KEY = "customInstructions";
1819
export const AIR_NATIVE_SUBAGENT_SESSIONS_KEY = "nativeSubagentSessions";
1920
export const AIR_ASYNC_TASKS_KEY = "asyncTasks";
2021
export const AIR_RECOMMENDED_CONFIG_VALUE_KEY = "recommendedValue";
@@ -97,6 +98,15 @@ export function clientSupportsAirCapability(
9798
&& supported.includes(capability);
9899
}
99100

101+
/** Read custom instructions from `session/new` metadata. */
102+
export function airCustomInstructions(meta: unknown): string | undefined {
103+
const root = asRecord(meta);
104+
const jetbrains = asRecord(root[JETBRAINS_META_KEY]);
105+
const air = asRecord(jetbrains[AIR_META_KEY]);
106+
const instructions = air[AIR_CUSTOM_INSTRUCTIONS_KEY];
107+
return typeof instructions === "string" ? instructions : undefined;
108+
}
109+
100110
function asRecord(value: unknown): Record<string, unknown> {
101111
return value !== null && typeof value === "object" && !Array.isArray(value)
102112
? value as Record<string, unknown>

‎src/CodexAcpClient.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ import {
7070
isUnknownThreadError,
7171
threadActiveWriterRequestError,
7272
} from "./CodexThreadErrors";
73+
import {airCustomInstructions} from "./AirExtension";
7374
export type {SessionMetadata, SessionMetadataWithThread} from "./SessionMetadata";
7475

7576
/**
@@ -749,13 +750,15 @@ export class CodexAcpClient {
749750

750751
async newSession(request: acp.NewSessionRequest): Promise<SessionMetadata> {
751752
const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
753+
const developerInstructions = airCustomInstructions(request._meta);
752754
await this.refreshSkills(request.cwd, additionalDirectories);
753755

754756
const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers);
755757
const response = await this.codexClient.threadStart({
756758
config: sessionConfig.config,
757759
modelProvider: this.getModelProvider(),
758760
cwd: request.cwd,
761+
...(developerInstructions !== undefined && {developerInstructions}),
759762
});
760763

761764
const codexModels = await this.fetchAvailableModels();

‎src/CodexAcpServer.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ import {TitleGenerator} from "./TitleGenerator";
146146
import {once} from "node:events";
147147
import {
148148
AIR_AGENT_FILE_CHANGE_REPORT_KEY,
149+
AIR_CUSTOM_INSTRUCTIONS_KEY,
149150
AIR_ASYNC_TASKS_KEY,
150151
AIR_CODEX_HOOKS_KEY,
151152
AIR_DIFF_PATCH_KEY,
@@ -482,6 +483,7 @@ export class CodexAcpServer {
482483
AIR_SESSION_FAILURE_KEY,
483484
AIR_DIFF_PATCH_KEY,
484485
AIR_AGENT_FILE_CHANGE_REPORT_KEY,
486+
AIR_CUSTOM_INSTRUCTIONS_KEY,
485487
AIR_NATIVE_SUBAGENT_SESSIONS_KEY,
486488
AIR_ASYNC_TASKS_KEY,
487489
AIR_RECOMMENDED_CONFIG_VALUE_KEY,

‎src/__tests__/CodexACPAgent/CodexAcpClient.test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -504,6 +504,64 @@ describe('ACP server test', { timeout: 40_000 }, () => {
504504
expect(listSkillsSpy).not.toHaveBeenCalled();
505505
});
506506

507+
it('passes AIR custom instructions to thread start', async () => {
508+
const mockFixture = createCodexMockTestFixture();
509+
const codexAcpClient = mockFixture.getCodexAcpClient();
510+
const codexAppServerClient = mockFixture.getCodexAppServerClient();
511+
vi.spyOn(codexAppServerClient, "listSkills").mockResolvedValue({data: []});
512+
const threadStartSpy = vi.spyOn(codexAppServerClient, "threadStart").mockResolvedValue({
513+
thread: {id: "thread-id"} as any,
514+
model: "gpt-5",
515+
reasoningEffort: "medium",
516+
serviceTier: null,
517+
} as any);
518+
vi.spyOn(codexAppServerClient, "listModels").mockResolvedValue({
519+
data: [createTestModel({id: "gpt-5"})],
520+
nextCursor: null,
521+
});
522+
523+
await codexAcpClient.newSession({
524+
cwd: "/workspace",
525+
mcpServers: [],
526+
_meta: {
527+
jetbrains: {
528+
air: {
529+
customInstructions: "Follow the project rules.",
530+
},
531+
},
532+
},
533+
});
534+
535+
expect(threadStartSpy).toHaveBeenCalledWith(expect.objectContaining({
536+
developerInstructions: "Follow the project rules.",
537+
}));
538+
});
539+
540+
it('ignores malformed AIR custom instructions', async () => {
541+
const mockFixture = createCodexMockTestFixture();
542+
const codexAcpClient = mockFixture.getCodexAcpClient();
543+
const codexAppServerClient = mockFixture.getCodexAppServerClient();
544+
vi.spyOn(codexAppServerClient, "listSkills").mockResolvedValue({data: []});
545+
const threadStartSpy = vi.spyOn(codexAppServerClient, "threadStart").mockResolvedValue({
546+
thread: {id: "thread-id"} as any,
547+
model: "gpt-5",
548+
reasoningEffort: "medium",
549+
serviceTier: null,
550+
} as any);
551+
vi.spyOn(codexAppServerClient, "listModels").mockResolvedValue({
552+
data: [createTestModel({id: "gpt-5"})],
553+
nextCursor: null,
554+
});
555+
556+
await codexAcpClient.newSession({
557+
cwd: "/workspace",
558+
mcpServers: [],
559+
_meta: {jetbrains: {air: {customInstructions: 42}}},
560+
});
561+
562+
expect(threadStartSpy.mock.calls[0]![0].developerInstructions).toBeUndefined();
563+
});
564+
507565
it('prefers ACP additional directories over legacy meta roots for new session skill discovery', async () => {
508566
const mockFixture = createCodexMockTestFixture();
509567
const codexAcpClient = mockFixture.getCodexAcpClient();

‎src/__tests__/CodexACPAgent/initialize.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ describe('CodexACPAgent - initialize', () => {
9191
controlMethod: "_session/goal",
9292
actions: ["set", "pause", "resume", "clear"],
9393
},
94-
capabilities: ["sessionFailure", "diffPatch", "agentFileChangeReport", "nativeSubagentSessions", "asyncTasks", "recommendedValue", "rawInputRendering", "planContentDelta", "codexHooks"],
94+
capabilities: ["sessionFailure", "diffPatch", "agentFileChangeReport", "customInstructions", "nativeSubagentSessions", "asyncTasks", "recommendedValue", "rawInputRendering", "planContentDelta", "codexHooks"],
9595
},
9696
},
9797
});

‎src/__tests__/scenarios/data/air/agent-message-and-reasoning.jsonl‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)