Add activation field to PromptSystemArgs for keyword-based system prompt activation (#1887)

Copilot · pelikhan · web-flow · commit 6b0bc7f61d85 · 2025-08-19T08:11:47.000-07:00
* Initial plan

* Add activation field to PromptSystemArgs and implement activation-based system resolution

Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;

* Complete implementation of activation field for system prompts with tests and integration

Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;

* Merge branch 'dev' into copilot/fix-e05d1306-4cde-4fa5-adce-543abae6d79c

* Add explanatory comment for word boundary regex in activation keyword matching

Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;

* Merge branch 'dev' into copilot/fix-e05d1306-4cde-4fa5-adce-543abae6d79c

* Add activation keywords for system.resources and support singular annotation

Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;
diff --git a/docs/public/genaiscript.d.ts b/docs/public/genaiscript.d.ts
diff --git a/docs/src/content/docs/reference/scripts/system.mdx b/docs/src/content/docs/reference/scripts/system.mdx
@@ -821,6 +821,7 @@ system({
     description:
         "GitHub Actions workflows support annotations ([Read more...](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message)).",
     lineNumbers: true,
+    activation: ["annotations", "warnings", "errors"],
 })
 
 export default function (ctx: ChatGenerationContext) {
@@ -926,6 +927,7 @@ Generate changelog formatter edits
 system({
     title: "Generate changelog formatter edits",
     lineNumbers: true,
+    activation: ["changelog"],
 })
 
 export default function (ctx: ChatGenerationContext) {
@@ -1074,6 +1076,7 @@ Generate diagrams
 `````js wrap title="system.diagrams"
 system({
   title: "Generate diagrams",
+  activation: ["diagram", "chart"],
   parameters: {
     repair: {
       type: "integer",
@@ -1357,6 +1360,7 @@ Teaches the file format supported by GenAIScripts
 system({
     title: "File generation",
     description: "Teaches the file format supported by GenAIScripts",
+    activation: ["file", "files"],
 })
 
 export default function (ctx: ChatGenerationContext) {
@@ -2130,6 +2134,7 @@ Git repository information
 `````js wrap title="system.git_info"
 system({
     title: "Git repository information",
+    activation: ["git"],
     parameters: {
         cwd: {
             type: "string",
@@ -2414,6 +2419,7 @@ General GitHub information.
 `````js wrap title="system.github_info"
 system({
     title: "General GitHub information.",
+    activation: ["github"],
 })
 
 export default async function (ctx: ChatGenerationContext) {
@@ -4734,6 +4740,7 @@ Today's date.
 `````js wrap title="system.today"
 system({
     title: "Today's date.",
+    activation: ["today"],
 })
 export default function (ctx: ChatGenerationContext) {
     const { $ } = ctx
diff --git a/packages/core/genaisrc/system.annotations.genai.mts b/packages/core/genaisrc/system.annotations.genai.mts
@@ -3,6 +3,7 @@ system({
     description:
         "GitHub Actions workflows support annotations ([Read more...](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message)).",
     lineNumbers: true,
+    activation: ["annotation", "annotations", "warnings", "errors"],
 })
 
 export default function (ctx: ChatGenerationContext) {
diff --git a/packages/core/genaisrc/system.changelog.genai.mts b/packages/core/genaisrc/system.changelog.genai.mts
@@ -1,6 +1,7 @@
 system({
     title: "Generate changelog formatter edits",
     lineNumbers: true,
+    activation: ["changelog"],
 })
 
 export default function (ctx: ChatGenerationContext) {
diff --git a/packages/core/genaisrc/system.diagrams.genai.mts b/packages/core/genaisrc/system.diagrams.genai.mts
@@ -1,5 +1,6 @@
 system({
   title: "Generate diagrams",
+  activation: ["diagram", "chart"],
   parameters: {
     repair: {
       type: "integer",
diff --git a/packages/core/genaisrc/system.files.genai.mts b/packages/core/genaisrc/system.files.genai.mts
@@ -1,6 +1,7 @@
 system({
     title: "File generation",
     description: "Teaches the file format supported by GenAIScripts",
+    activation: ["file", "files"],
 })
 
 export default function (ctx: ChatGenerationContext) {
diff --git a/packages/core/genaisrc/system.git_info.genai.mts b/packages/core/genaisrc/system.git_info.genai.mts
@@ -1,5 +1,6 @@
 system({
     title: "Git repository information",
+    activation: ["git"],
     parameters: {
         cwd: {
             type: "string",
diff --git a/packages/core/genaisrc/system.github_info.genai.mts b/packages/core/genaisrc/system.github_info.genai.mts
@@ -1,5 +1,6 @@
 system({
     title: "General GitHub information.",
+    activation: ["github"],
 })
 
 export default async function (ctx: ChatGenerationContext) {
diff --git a/packages/core/genaisrc/system.resources.genai.mts b/packages/core/genaisrc/system.resources.genai.mts
@@ -2,6 +2,7 @@ system({
   title: "Read resource content from a URL using MCP resource resolution",
   description:
     "Provides a tool that can read and return the content of resources from URLs using the host's resolveResource function. Supports various protocols including https, file, git, gist, and vscode.",
+  activation: ["resource", "resources"],
 });
 
 export default function (ctx: ChatGenerationContext) {
diff --git a/packages/core/genaisrc/system.today.genai.mts b/packages/core/genaisrc/system.today.genai.mts
@@ -1,5 +1,6 @@
 system({
     title: "Today's date.",
+    activation: ["today"],
 })
 export default function (ctx: ChatGenerationContext) {
     const { $ } = ctx
diff --git a/packages/core/src/systems.ts b/packages/core/src/systems.ts
@@ -86,44 +86,15 @@ export function resolveSystems(
       dbgr(`images found, adding system.safety_harmful_content`);
       systems.push("system.safety_harmful_content");
     }
-    // Determine additional systems based on content of jsSource
-    if (/\Wfile\W/i.test(jsSource)) {
-      dbgr(`file references found, adding system.files`);
-      systems.push("system.files");
-      // Add file schema system if schema is used
-      if (useSchema) {
-        dbgr(`schema is used, adding system.files_schema`);
-        systems.push("system.files_schema");
-      }
-    }
-    if (/\Wchangelog\W/i.test(jsSource)) {
-      dbgr(`changelog references found, adding system.changelog`);
-      systems.push("system.changelog");
-    }
     // Add schema system if schema is used
     if (useSchema) {
       dbgr(`schema is used, adding system.schema`);
       systems.push("system.schema");
     }
-    // Add annotation system if annotations, warnings, or errors are found
-    if (/\W(annotations|warnings|errors)\W/i.test(jsSource)) {
-      dbgr(`annotations, warnings, or errors found, adding system.annotations`);
-      systems.push("system.annotations");
-    }
-    // Add diagram system if diagrams or charts are found
-    if (/\W(diagram|chart)\W/i.test(jsSource)) {
-      dbgr(`diagrams or charts found, adding system.diagrams`);
-      systems.push("system.diagrams");
-    }
-    // Add git information system if git is found
-    if (/\W(git)\W/i.test(jsSource)) {
-      dbgr(`git references found, adding system.git_info`);
-      systems.push("system.git_info");
-    }
-    // Add GitHub information system if GitHub is found
-    if (/\W(github)\W/i.test(jsSource)) {
-      dbgr(`GitHub references found, adding system.github_info`);
-      systems.push("system.github_info");
+    // Add file schema system if schema is used and files are referenced
+    if (/\Wfile\W/i.test(jsSource) && useSchema) {
+      dbgr(`schema is used with files, adding system.files_schema`);
+      systems.push("system.files_schema");
     }
     // Add programming language system prompts based on file extensions or language keywords
     if (/\.(go)$|golang|go\s/i.test(jsSource)) {
@@ -150,10 +121,23 @@ export function resolveSystems(
       dbgr(`PHP references found, adding system.php`);
       systems.push("system.php");
     }
-    // Add system.today if "today" is found in jsSource
-    if (/today/i.test(jsSource)) {
-      dbgr(`adding system.today to systems`);
-      systems.push("system.today");
+    // Check activation keywords from system prompts in the project
+    if (prj?.scripts && jsSource) {
+      const systemPrompts = prj.scripts.filter((s) => s.isSystem);
+      for (const systemPrompt of systemPrompts) {
+        const activationKeywords = arrayify(systemPrompt.activation);
+        if (activationKeywords.length > 0) {
+          // Check if any activation keyword matches the jsSource
+          for (const keyword of activationKeywords) {
+            // Use word boundary \b to match complete words only, not subwords (e.g., "file" matches "file" but not "profile")
+            if (keyword && new RegExp(`\\b${keyword}`, 'i').test(jsSource)) {
+              dbgr(`activation keyword "${keyword}" found, adding ${systemPrompt.id}`);
+              systems.push(systemPrompt.id);
+              break; // Only add the system once even if multiple keywords match
+            }
+          }
+        }
+      }
     }
   }
 
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -484,6 +484,12 @@ export interface PromptSystemOptions extends PromptSystemSafetyOptions {
    */
   excludedSystem?: ElementOrArray<SystemPromptId>;
 
+  /**
+   * Keywords that will 'activate' the system script. When these keywords are found in the prompt source, 
+   * the system script will be automatically imported.
+   */
+  activation?: ElementOrArray<string>;
+
   /**
    * MCP server configuration. The tools will be injected into the prompt.
    */
diff --git a/packages/core/test/activation.integration.test.ts b/packages/core/test/activation.integration.test.ts
@@ -0,0 +1,160 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * Integration test to demonstrate the activation field functionality.
+ * This test validates that system prompts are correctly activated based on their activation keywords.
+ */
+
+import { describe, test, assert } from "vitest";
+import { resolveSystems } from "../src/systems.js";
+import type { Project } from "../src/server/messages.js";
+import type { PromptScript } from "../src/types.js";
+
+describe("activation field integration", () => {
+  test("should demonstrate activation field working with realistic example", () => {
+    // Create a realistic scenario with multiple system prompts
+    const projectScripts: PromptScript[] = [
+      // System prompts with activation keywords
+      {
+        id: "system.files",
+        title: "File generation system",
+        isSystem: true,
+        activation: ["file", "files", "filesystem"],
+      } as PromptScript,
+      {
+        id: "system.git_info",
+        title: "Git information system",
+        isSystem: true,
+        activation: ["git", "repository", "commit"],
+      } as PromptScript,
+      {
+        id: "system.annotations",
+        title: "Code annotations system",
+        isSystem: true,
+        activation: ["error", "warning", "annotation"],
+      } as PromptScript,
+      // System prompt without activation (shouldn't be auto-activated)
+      {
+        id: "system.manual_only",
+        title: "Manual activation only",
+        isSystem: true,
+        // No activation field
+      } as PromptScript,
+      // Regular prompt (not a system prompt)
+      {
+        id: "regular.prompt",
+        title: "Regular prompt",
+        isSystem: false,
+        activation: ["should", "not", "matter"],
+      } as PromptScript,
+    ];
+
+    const project: Project = {
+      scripts: projectScripts,
+      diagnostics: [],
+    };
+
+    // Test scenario: User writes a script that references files and git
+    const userScript = {
+      jsSource: `
+        // Read configuration file
+        const config = file.readText("config.json");
+        
+        // Get current git branch
+        const branch = git.branch();
+        
+        console.log("Processing files on branch:", branch);
+      `,
+    };
+
+    const resolvedSystems = resolveSystems(project, userScript);
+    const systemIds = resolvedSystems.map(s => s.id);
+
+    // Should activate system.files because "file" appears in jsSource
+    assert.include(systemIds, "system.files", "Should activate system.files due to 'file' keyword");
+    
+    // Should activate system.git_info because "git" appears in jsSource  
+    assert.include(systemIds, "system.git_info", "Should activate system.git_info due to 'git' keyword");
+    
+    // Should NOT activate system.annotations because no relevant keywords appear
+    assert.notInclude(systemIds, "system.annotations", "Should not activate system.annotations - no relevant keywords");
+    
+    // Should NOT activate system.manual_only because it has no activation keywords
+    assert.notInclude(systemIds, "system.manual_only", "Should not activate system.manual_only - no activation keywords");
+    
+    // Should NOT include regular prompts
+    assert.notInclude(systemIds, "regular.prompt", "Should not include non-system prompts");
+  });
+
+  test("should preserve explicit system configuration when provided", () => {
+    const projectScripts: PromptScript[] = [
+      {
+        id: "system.files",
+        title: "File generation system",
+        isSystem: true,
+        activation: ["file", "files"],
+      } as PromptScript,
+      {
+        id: "system.custom",
+        title: "Custom system prompt",
+        isSystem: true,
+        // No activation keywords
+      } as PromptScript,
+    ];
+
+    const project: Project = {
+      scripts: projectScripts,
+      diagnostics: [],
+    };
+
+    // When user explicitly specifies system prompts, activation should be bypassed
+    const userScriptWithExplicitSystem = {
+      jsSource: "const data = file.readText('data.txt');", // Contains "file" keyword
+      system: ["system.custom"], // Explicitly specified
+    };
+
+    const resolvedSystems = resolveSystems(project, userScriptWithExplicitSystem);
+    const systemIds = resolvedSystems.map(s => s.id);
+
+    // Should include explicitly specified system
+    assert.include(systemIds, "system.custom", "Should include explicitly specified system");
+    
+    // Should NOT include auto-activated systems when explicit system is provided
+    assert.notInclude(systemIds, "system.files", "Should not auto-activate when explicit system is provided");
+  });
+
+  test("should handle multiple activation keywords for same system", () => {
+    const projectScripts: PromptScript[] = [
+      {
+        id: "system.development",
+        title: "Development tools system",
+        isSystem: true,
+        activation: ["code", "debug", "test", "build", "compile"],
+      } as PromptScript,
+    ];
+
+    const project: Project = {
+      scripts: projectScripts,
+      diagnostics: [],
+    };
+
+    // Test different keywords that should all activate the same system
+    const testCases = [
+      "Write some code for the project",
+      "Debug the application",
+      "Run the test suite", 
+      "Build the application",
+      "Compile the source files",
+    ];
+
+    for (const jsSource of testCases) {
+      const script = { jsSource };
+      const resolvedSystems = resolveSystems(project, script);
+      const systemIds = resolvedSystems.map(s => s.id);
+      
+      assert.include(systemIds, "system.development", 
+        `Should activate system.development for: "${jsSource}"`);
+    }
+  });
+});
diff --git a/packages/core/test/systems.test.ts b/packages/core/test/systems.test.ts
