@compilr-dev/sdk 0.22.0 → 0.23.1

package/dist/team/custom-agents.d.ts

@@ -33,6 +33,36 @@ export declare const CUSTOM_MASCOTS: string[];
  * Avoids mascots already in use by other custom agents.
  */
 export declare function assignMascot(existingAgents: CustomAgentDefinition[]): string;
+/**
+ * The generated scaffold for a custom agent: who it is and what it sticks to.
+ *
+ * ⚠️ COMPOSED AT `TeamAgent.initialize()`, NEVER STORED in `systemPromptAddition`. That field
+ * is the user's own words and nothing else — a host that renders it in a textarea (both of ours
+ * do) must not be shown machine-written prose to hand-edit, and must not freeze it on save.
+ */
+export declare function generateCustomAgentScaffold(displayName: string, specialty: string): string;
+/** What a legacy composite yielded up: the user's own words, and a personality to rescue. */
+export interface LegacyCustomPromptParts {
+    /** The text the user actually typed, or undefined if they never typed any. */
+    userText?: string;
+    /** Personality recovered from a frozen `Your approach:` line — see below. */
+    personality?: string;
+}
+/**
+ * Split a pre-0.23 custom-agent composite back into the parts that belong to the user.
+ *
+ * Before this change `fromCustomDefinition` stored the whole generated composite in
+ * `systemPromptAddition`, so every agent already on disk has it frozen there. This reverses that
+ * for the fields we can recover without guessing.
+ *
+ * ⚠️ `personality` is recovered, not discarded. Legacy `fromCustomDefinition` never passed the
+ * definition's personality to the live agent, so for these agents the ONLY surviving copy is the
+ * `Your approach:` line inside this string. Dropping it would silently delete a value the user set.
+ *
+ * Returns `{}` when the string does not look like a composite, which is the signal to leave the
+ * stored value exactly as it is. Guessing is worse than migrating nothing.
+ */
+export declare function splitLegacyCustomPrompt(stored: string): LegacyCustomPromptParts;
 /**
  * Generate system prompt for a custom agent.
  * Uses a template-based approach (no LLM call).

package/dist/team/custom-agents.js

@@ -49,6 +49,57 @@ export function assignMascot(existingAgents) {
 // =============================================================================
 // System Prompt Generation
 // =============================================================================
+/**
+ * The generated scaffold for a custom agent: who it is and what it sticks to.
+ *
+ * ⚠️ COMPOSED AT `TeamAgent.initialize()`, NEVER STORED in `systemPromptAddition`. That field
+ * is the user's own words and nothing else — a host that renders it in a textarea (both of ours
+ * do) must not be shown machine-written prose to hand-edit, and must not freeze it on save.
+ */
+export function generateCustomAgentScaffold(displayName, specialty) {
+    return [
+        `You are a ${displayName} specialized in ${specialty}.`,
+        '',
+        'Focus on your area of expertise. When questions fall outside your specialty, suggest which team member might be better suited to help.',
+    ].join('\n');
+}
+/**
+ * Split a pre-0.23 custom-agent composite back into the parts that belong to the user.
+ *
+ * Before this change `fromCustomDefinition` stored the whole generated composite in
+ * `systemPromptAddition`, so every agent already on disk has it frozen there. This reverses that
+ * for the fields we can recover without guessing.
+ *
+ * ⚠️ `personality` is recovered, not discarded. Legacy `fromCustomDefinition` never passed the
+ * definition's personality to the live agent, so for these agents the ONLY surviving copy is the
+ * `Your approach:` line inside this string. Dropping it would silently delete a value the user set.
+ *
+ * Returns `{}` when the string does not look like a composite, which is the signal to leave the
+ * stored value exactly as it is. Guessing is worse than migrating nothing.
+ */
+export function splitLegacyCustomPrompt(stored) {
+    // The identity line is what makes this recognisable as generated. No line, no migration.
+    if (!/^You are a .+ specialized in .+\.$/m.test(stored))
+        return {};
+    const parts = {};
+    const approach = /^Your approach: (.+)$/m.exec(stored);
+    if (approach)
+        parts.personality = approach[1].trim();
+    const marker = '## Custom Instructions\n\n';
+    const at = stored.indexOf(marker);
+    if (at !== -1) {
+        let body = stored.slice(at + marker.length);
+        // Tool awareness, when present, was appended after a `---` rule. Everything from there on
+        // is generated too.
+        const rule = body.indexOf('\n\n---\n\n');
+        if (rule !== -1)
+            body = body.slice(0, rule);
+        const trimmed = body.trim();
+        if (trimmed)
+            parts.userText = trimmed;
+    }
+    return parts;
+}
 /**
  * Generate system prompt for a custom agent.
  * Uses a template-based approach (no LLM call).
@@ -56,10 +107,6 @@ export function assignMascot(existingAgents) {
  */
 export function generateCustomAgentSystemPrompt(agent) {
     const lines = [`You are a ${agent.displayName} specialized in ${agent.specialty}.`];
-    if (agent.personality) {
-        lines.push('');
-        lines.push(`Your approach: ${agent.personality}`);
-    }
     lines.push('');
     lines.push('Focus on your area of expertise. When questions fall outside your specialty, suggest which team member might be better suited to help.');
     // Append custom instructions if provided

package/dist/team/team-agent.d.ts

@@ -13,6 +13,38 @@ import type { ModelTier } from '../models/index.js';
 import type { ProviderType } from '../config.js';
 import type { SharedContextManager } from './shared-context.js';
 import type { CustomAgentDefinition } from './custom-agents.js';
+/**
+ * Strip the composite a pre-0.23 `fromRole()` stored, so it is not composed a second time.
+ *
+ * ⚠️ WITHOUT THIS, EVERY ROLE AGENT CREATED BEFORE 0.23 SENDS ITS ROLE PROMPT TWICE. The first
+ * cut of this migration skipped role agents, reasoning that an edited stored prompt is
+ * indistinguishable from an unedited one so removing anything risks the user's text. True, and
+ * beside the point: the generated sections now compose on top of whatever is stored, so leaving
+ * the legacy copy in place duplicates it. Measured on a real `$arch`: 13,024 characters instead
+ * of ~6,900, with the role header and capability blurb appearing twice each.
+ *
+ * ⚠️ AND IT CANNOT WORK BY RECONSTRUCTION. The second cut rebuilt the old composite exactly and
+ * stripped it on an exact match. That matched 6 of 16 real agents. The capability blurb lists
+ * the profile's tool GROUPS as they stood on the day the agent was created — a `qa` agent saved
+ * before the profile gained `consult` carries a blurb nine characters shorter than today's, and
+ * no amount of care reproduces a list that has since changed.
+ *
+ * So this anchors on the two ends, which are stable, and ignores the drifting middle entirely:
+ *
+ *   - the FIRST LINE must be the first line of generated content (the role header, or the
+ *     guidance heading for roles with no role prompt of their own), and
+ *   - the CURRENT guidance block must appear — it is always last, and unlike the tool blurb it
+ *     is not derived from mutable configuration.
+ *
+ * Everything up to the end of that guidance is generated; whatever follows is the user's and is
+ * kept. If either anchor is missing the value is returned untouched, so hand-written text and a
+ * future rewording both fail safe: the agent keeps its duplication until someone clears the box,
+ * and nobody loses text they wrote.
+ *
+ * @returns the user's own remainder, `undefined` if the stored value was entirely generated, or
+ *          `stored` unchanged when it is not recognisably a legacy composite.
+ */
+export declare function splitLegacyRolePrompt(stored: string, role: AgentRole): string | undefined;
 /**
  * The editable subset of an agent.
  *
@@ -147,6 +179,12 @@ export declare class TeamAgent {
      * Tool profile name (for display)
      */
     toolProfile?: TeamAgentConfig['toolProfile'];
+    /**
+     * Groups behind a `custom` profile. Needed because the capability blurb is now composed on
+     * every build rather than baked once, and a custom profile's blurb cannot be regenerated
+     * from the profile name alone.
+     */
+    customGroups?: string[];
     /**
      * Enabled skills (empty = all skills)
      */
@@ -248,6 +286,25 @@ export declare class TeamAgent {
     applyUpdate(patch: TeamAgentUpdate): {
         rebuilt: boolean;
     };
+    /**
+     * The generated half of the prompt, rebuilt from CURRENT state on every build.
+     *
+     * ⚠️ THIS IS WHY IT IS A METHOD AND NOT A STORED STRING. All three constructors used to bake
+     * these sections into `systemPromptAddition`, which broke three ways at once:
+     *
+     *   1. hosts render that field in a textarea, so users were shown generated prose to hand-edit
+     *      (`fromRole('pm')` alone put 6,321 characters of role prompt in there) and their save
+     *      froze it as if they had written it;
+     *   2. a custom agent's personality was baked in as `Your approach:` while an edit appended
+     *      `Your manner:` — so editing it added a contradiction instead of changing it;
+     *   3. the capability blurb described whatever profile the agent had AT CREATION, so changing
+     *      the tool profile updated the filter but left the prompt telling the agent it still had
+     *      tools it no longer had.
+     *
+     * Composing here fixes all three: nothing generated is ever stored, and every section reflects
+     * the state at the moment the agent is built.
+     */
+    private generatedPromptSections;
     /**
      * Initialize the agent with the given factory
      * This allows the team to control agent creation

package/dist/team/team-agent.js

@@ -9,8 +9,60 @@
  */
 import { ROLE_METADATA } from './types.js';
 import { getModelForTier, getModelContextWindow } from '../models/index.js';
-import { generateCustomAgentSystemPrompt, getCustomAgentToolFilter } from './custom-agents.js';
+import { generateCustomAgentScaffold, getCustomAgentToolFilter, splitLegacyCustomPrompt, } from './custom-agents.js';
 import { getToolsForProfile, PROFILE_INFO, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+/**
+ * Strip the composite a pre-0.23 `fromRole()` stored, so it is not composed a second time.
+ *
+ * ⚠️ WITHOUT THIS, EVERY ROLE AGENT CREATED BEFORE 0.23 SENDS ITS ROLE PROMPT TWICE. The first
+ * cut of this migration skipped role agents, reasoning that an edited stored prompt is
+ * indistinguishable from an unedited one so removing anything risks the user's text. True, and
+ * beside the point: the generated sections now compose on top of whatever is stored, so leaving
+ * the legacy copy in place duplicates it. Measured on a real `$arch`: 13,024 characters instead
+ * of ~6,900, with the role header and capability blurb appearing twice each.
+ *
+ * ⚠️ AND IT CANNOT WORK BY RECONSTRUCTION. The second cut rebuilt the old composite exactly and
+ * stripped it on an exact match. That matched 6 of 16 real agents. The capability blurb lists
+ * the profile's tool GROUPS as they stood on the day the agent was created — a `qa` agent saved
+ * before the profile gained `consult` carries a blurb nine characters shorter than today's, and
+ * no amount of care reproduces a list that has since changed.
+ *
+ * So this anchors on the two ends, which are stable, and ignores the drifting middle entirely:
+ *
+ *   - the FIRST LINE must be the first line of generated content (the role header, or the
+ *     guidance heading for roles with no role prompt of their own), and
+ *   - the CURRENT guidance block must appear — it is always last, and unlike the tool blurb it
+ *     is not derived from mutable configuration.
+ *
+ * Everything up to the end of that guidance is generated; whatever follows is the user's and is
+ * kept. If either anchor is missing the value is returned untouched, so hand-written text and a
+ * future rewording both fail safe: the agent keeps its duplication until someone clears the box,
+ * and nobody loses text they wrote.
+ *
+ * @returns the user's own remainder, `undefined` if the stored value was entirely generated, or
+ *          `stored` unchanged when it is not recognisably a legacy composite.
+ */
+export function splitLegacyRolePrompt(stored, role) {
+    /*
+      ⚠️ TYPED AS TOTAL, NOT TOTAL AT RUNTIME. `role` is `AgentRole` to the compiler but arrives
+      from a JSON file on disk, so it can be any string — a role removed in a later version, or one
+      a fixture invented. The explicit `| undefined` is what makes the guard below legitimate
+      rather than "always falsy": lint reasons from the type, and the type is a claim about data
+      we do not control.
+    */
+    const byRole = ROLE_METADATA;
+    const metadata = byRole[role];
+    if (!metadata)
+        return stored;
+    const guidance = role === 'default' ? generateCoordinatorGuidance() : generateSpecialistGuidance(role);
+    const generatedFirstLine = (metadata.defaultSystemPromptAddition || guidance).split('\n')[0];
+    if (stored.split('\n')[0] !== generatedFirstLine)
+        return stored;
+    const at = stored.lastIndexOf(guidance);
+    if (at === -1)
+        return stored;
+    return stored.slice(at + guidance.length).trim() || undefined;
+}
 /**
  * Estimate token count from text (approximate: ~4 chars per token)
  */
@@ -145,6 +197,12 @@ export class TeamAgent {
      * Tool profile name (for display)
      */
     toolProfile;
+    /**
+     * Groups behind a `custom` profile. Needed because the capability blurb is now composed on
+     * every build rather than baked once, and a custom profile's blurb cannot be regenerated
+     * from the profile name alone.
+     */
+    customGroups;
     /**
      * Enabled skills (empty = all skills)
      */
@@ -202,6 +260,7 @@ export class TeamAgent {
         this.noTools = config.noTools;
         this.toolFilter = config.toolFilter;
         this.toolProfile = config.toolProfile;
+        this.customGroups = config.customGroups;
         this.enabledSkills = config.enabledSkills;
         this.personality = config.personality;
         this.autoApproveHandoff = config.autoApproveHandoff;
@@ -341,6 +400,48 @@ export class TeamAgent {
             this.stashForRebuild();
         return { rebuilt: needsRebuild || tierChanged };
     }
+    /**
+     * The generated half of the prompt, rebuilt from CURRENT state on every build.
+     *
+     * ⚠️ THIS IS WHY IT IS A METHOD AND NOT A STORED STRING. All three constructors used to bake
+     * these sections into `systemPromptAddition`, which broke three ways at once:
+     *
+     *   1. hosts render that field in a textarea, so users were shown generated prose to hand-edit
+     *      (`fromRole('pm')` alone put 6,321 characters of role prompt in there) and their save
+     *      froze it as if they had written it;
+     *   2. a custom agent's personality was baked in as `Your approach:` while an edit appended
+     *      `Your manner:` — so editing it added a contradiction instead of changing it;
+     *   3. the capability blurb described whatever profile the agent had AT CREATION, so changing
+     *      the tool profile updated the filter but left the prompt telling the agent it still had
+     *      tools it no longer had.
+     *
+     * Composing here fixes all three: nothing generated is ever stored, and every section reflects
+     * the state at the moment the agent is built.
+     */
+    generatedPromptSections() {
+        const sections = [];
+        if (this.role === 'custom') {
+            sections.push(generateCustomAgentScaffold(this.displayName, this.description ?? ''));
+        }
+        else {
+            const roleScaffold = ROLE_METADATA[this.role].defaultSystemPromptAddition;
+            if (roleScaffold)
+                sections.push(roleScaffold);
+        }
+        // Capability blurb — from the live profile, never a baked copy (defect 3 above).
+        const profile = this.toolProfile;
+        if (profile && profile !== 'full') {
+            sections.push(generateToolAwarenessPrompt({ profile, customGroups: this.customGroups }));
+        }
+        // Delegation guidance. Custom agents never had it and still do not — this method reproduces
+        // what each constructor built, it does not redistribute behaviour between roles.
+        if (this.role !== 'custom') {
+            sections.push(this.role === 'default'
+                ? generateCoordinatorGuidance()
+                : generateSpecialistGuidance(this.role));
+        }
+        return sections;
+    }
     /**
      * Initialize the agent with the given factory
      * This allows the team to control agent creation
@@ -352,8 +453,13 @@ export class TeamAgent {
         if (this._agent) {
             return; // Already initialized
         }
-        // Build system prompt addition with shared context
-        let finalSystemPromptAddition = this.systemPromptAddition ?? '';
+        /*
+          Generated sections first, then the user's own words. `systemPromptAddition` holds ONLY what
+          the user typed — see `generatedPromptSections()` for why nothing generated is stored.
+        */
+        let finalSystemPromptAddition = [...this.generatedPromptSections(), this.systemPromptAddition]
+            .filter((section) => Boolean(section?.trim()))
+            .join('\n\n');
         // Identity preamble — every team agent gets a stable self-reference
         // block at the top of its prompt addition. Without this, the agent
         // knows it's "the PM" from the role prompt but doesn't connect that
@@ -575,6 +681,7 @@ export class TeamAgent {
             noTools: this.noTools,
             toolFilter: this.toolFilter,
             toolProfile: this.toolProfile,
+            customGroups: this.customGroups,
             enabledSkills: this.enabledSkills,
             modelTier: this.modelTier,
             autoApproveHandoff: this.autoApproveHandoff,
@@ -588,18 +695,49 @@ export class TeamAgent {
         // Refresh tool filter from profile if available (ensures new tools are picked up)
         // This handles the case where tools were added after the agent was created
         const toolFilter = data.toolProfile ? getToolsForProfile(data.toolProfile) : data.toolFilter;
+        /*
+          MIGRATION — agents serialized before generated text was separated out.
+          Their `systemPromptAddition` holds the whole generated composite, because that is what the
+          constructors used to store. Recover the parts that are genuinely the user's.
+    
+          ⚠️ THE FAILURE MODE IS "CHANGE NOTHING", NEVER "GUESS". `splitLegacyCustomPrompt` returns an
+          empty result for anything it does not positively recognise, and we then keep the stored
+          string exactly as it is — which is the pre-migration behaviour. A generator that has since
+          changed wording costs one agent a stale prompt until its next edit; a clever guess would
+          cost the user the instructions they wrote.
+    
+          Role agents are deliberately NOT migrated. Their stored string is generated in full, but an
+          edited one is indistinguishable from an unedited one, so anything removed might be the
+          user's. Their generated sections now compose on top of whatever is stored: a legacy role
+          agent shows its old prompt in the editor until someone clears it, and nothing is lost.
+        */
+        let systemPromptAddition = data.systemPromptAddition;
+        let personality = data.personality;
+        if (data.role === 'custom' && systemPromptAddition) {
+            const legacy = splitLegacyCustomPrompt(systemPromptAddition);
+            if (legacy.userText !== undefined || legacy.personality !== undefined) {
+                systemPromptAddition = legacy.userText;
+                // Only rescue the baked personality when the live field never held one — a value set
+                // through the editor is newer than anything frozen in the prompt.
+                personality = personality ?? legacy.personality;
+            }
+        }
+        else if (data.role !== 'custom' && systemPromptAddition) {
+            systemPromptAddition = splitLegacyRolePrompt(systemPromptAddition, data.role);
+        }
         const agent = new TeamAgent({
             id: data.id,
             displayName: data.displayName,
             mascot: data.mascot,
             role: data.role,
             description: data.description,
-            systemPromptAddition: data.systemPromptAddition,
-            personality: data.personality,
+            systemPromptAddition,
+            personality,
             useMinimalSystemPrompt: data.useMinimalSystemPrompt,
             noTools: data.noTools,
             toolFilter,
             toolProfile: data.toolProfile,
+            customGroups: data.customGroups,
             enabledSkills: data.enabledSkills,
             modelTier: data.modelTier,
             autoApproveHandoff: data.autoApproveHandoff,
@@ -619,36 +757,14 @@ export class TeamAgent {
         // Get tool filter from default profile (if specified)
         const profile = metadata.defaultToolProfile;
         const toolFilter = profile ? getToolsForProfile(profile) : undefined;
-        // Build system prompt with tool awareness (for non-full profiles)
-        let systemPromptAddition = metadata.defaultSystemPromptAddition ?? '';
-        if (profile && profile !== 'full') {
-            const toolAwareness = generateToolAwarenessPrompt({ profile });
-            systemPromptAddition = systemPromptAddition
-                ? `${systemPromptAddition}\n\n${toolAwareness}`
-                : toolAwareness;
-        }
-        // Add delegation guidance based on role
-        if (role === 'default') {
-            // Coordinator gets delegation tool guidance
-            const coordinatorGuidance = generateCoordinatorGuidance();
-            systemPromptAddition = systemPromptAddition
-                ? `${systemPromptAddition}\n\n${coordinatorGuidance}`
-                : coordinatorGuidance;
-        }
-        else {
-            // Specialists get collaboration guidance
-            const specialistGuidance = generateSpecialistGuidance(role);
-            systemPromptAddition = systemPromptAddition
-                ? `${systemPromptAddition}\n\n${specialistGuidance}`
-                : specialistGuidance;
-        }
+        // The role prompt, capability blurb and delegation guidance are all generated, so they are
+        // composed at initialize() rather than stored. A fresh role agent has no user text at all.
         return new TeamAgent({
             id: id ?? role,
             displayName: metadata.displayName,
             mascot: metadata.mascot,
             role,
             description: metadata.description,
-            systemPromptAddition: systemPromptAddition || undefined,
             useMinimalSystemPrompt: metadata.useMinimalSystemPrompt,
             noTools: metadata.noTools,
             toolFilter,
@@ -667,31 +783,15 @@ export class TeamAgent {
         const metadata = ROLE_METADATA[baseRole];
         const profile = opts.toolProfile ?? metadata.defaultToolProfile;
         const toolFilter = profile ? getToolsForProfile(profile) : undefined;
-        // Base role prompt + the specialist addition (specialization on top of role).
-        let systemPromptAddition = metadata.defaultSystemPromptAddition ?? '';
-        if (opts.systemPromptAddition?.trim()) {
-            systemPromptAddition = systemPromptAddition
-                ? `${systemPromptAddition}\n\n${opts.systemPromptAddition.trim()}`
-                : opts.systemPromptAddition.trim();
-        }
-        if (profile && profile !== 'full') {
-            const toolAwareness = generateToolAwarenessPrompt({ profile });
-            systemPromptAddition = systemPromptAddition
-                ? `${systemPromptAddition}\n\n${toolAwareness}`
-                : toolAwareness;
-        }
-        // Specialists always get collaboration guidance (never the coordinator path).
-        const specialistGuidance = generateSpecialistGuidance(baseRole);
-        systemPromptAddition = systemPromptAddition
-            ? `${systemPromptAddition}\n\n${specialistGuidance}`
-            : specialistGuidance;
+        // Only the specialist's own addition is authored text; the role prompt, capability blurb and
+        // collaboration guidance are generated and composed at initialize().
         return new TeamAgent({
             id: opts.id ?? baseRole,
             displayName: opts.displayName ?? metadata.displayName,
             mascot: metadata.mascot,
             role: baseRole,
             description: metadata.description,
-            systemPromptAddition: systemPromptAddition || undefined,
+            systemPromptAddition: opts.systemPromptAddition?.trim() || undefined,
             useMinimalSystemPrompt: metadata.useMinimalSystemPrompt,
             noTools: metadata.noTools,
             toolFilter,
@@ -711,9 +811,16 @@ export class TeamAgent {
             mascot: def.mascot,
             role: 'custom',
             description: def.specialty,
-            systemPromptAddition: generateCustomAgentSystemPrompt(def),
+            // The user's own words only — the identity and focus lines are composed at initialize().
+            systemPromptAddition: def.systemPromptAddition,
+            /* ⚠️ WITHOUT THIS an edit ADDS a second personality instead of changing the one in force:
+               the definition's value was baked into the prompt as `Your approach:` and never reached
+               the live field, so `updateAgent({ personality })` appended a contradicting `Your manner:`
+               while the original stayed active. */
+            personality: def.personality,
             toolFilter, // Pass tool filter from custom agent config
             toolProfile: def.toolConfig?.profile, // Store profile for display
+            customGroups: def.toolConfig?.customGroups,
             enabledSkills: def.enabledSkills, // Store skills for display
             modelTier: def.modelTier, // Store model tier
         });

package/dist/team/types.d.ts

@@ -135,6 +135,8 @@ export interface TeamAgentConfig {
      * Shows which profile was selected when creating the agent
      */
     toolProfile?: ToolProfile;
+    /** Groups behind a `custom` profile — see TeamAgent.customGroups. */
+    customGroups?: string[];
     /**
      * Enabled skills for this agent
      * Empty array means all skills, non-empty means filtered
@@ -173,6 +175,7 @@ export interface SerializedTeamAgent {
     noTools?: boolean;
     toolFilter?: string[];
     toolProfile?: ToolProfile;
+    customGroups?: string[];
     enabledSkills?: string[];
     modelTier?: ModelTier;
     autoApproveHandoff?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",