@compilr-dev/sdk 0.18.11 → 0.20.0

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

@@ -13,22 +13,78 @@ 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';
+/**
+ * The editable subset of an agent.
+ *
+ * ⚠️ `id` AND `role` ARE ABSENT BY DESIGN. The id is immutable (see `TeamAgent.id`); the role
+ * is structural — it decides the preset an agent was built from, and the editor's five
+ * sections do not offer it.
+ */
+export interface TeamAgentUpdate {
+    displayName?: string;
+    mascot?: MascotExpression;
+    description?: string;
+    systemPromptAddition?: string;
+    toolProfile?: TeamAgentConfig['toolProfile'];
+    toolFilter?: string[];
+    enabledSkills?: string[];
+}
+/** What an edit did, and whether anyone needs telling. */
+export interface AgentUpdateResult {
+    /** The underlying agent was dropped and rebuilt, carrying its history across. */
+    rebuilt: boolean;
+    /**
+     * ⚠️ THE CASE THAT HAS TO REACH THE CONVERSATION. The agent may now touch strictly less
+     * than it could — and its own history contains it planning to do things it can no longer
+     * do. Its next turn will attempt one and get a refusal it cannot account for: a capability
+     * change an agent cannot OBSERVE reads to it as a malfunction.
+     *
+     * Widening is reported too. Nothing breaks, but a record of when an agent gained the
+     * ability to write files is worth more than the row it costs.
+     */
+    toolsNarrowed: boolean;
+    previousProfile?: TeamAgentConfig['toolProfile'];
+    newProfile?: TeamAgentConfig['toolProfile'];
+}
+/**
+ * Did the tool profile get strictly smaller?
+ *
+ * ⚠️ Decided by whether the profile is READ-ONLY, not by counting tools. A profile with more
+ * tools that cannot write is a narrowing in every sense the user cares about, and tool counts
+ * shift whenever the registry grows.
+ */
+export declare function isNarrowing(before: TeamAgentConfig['toolProfile'], after: TeamAgentConfig['toolProfile']): boolean;
 /**
  * TeamAgent wraps an Agent instance with team-specific metadata
  */
 export declare class TeamAgent {
     /**
-     * Unique identifier (e.g., 'pm', 'arch', 'qa')
+     * Unique identifier (e.g., 'pm', 'arch', 'qa').
+     *
+     * ⚠️ IMMUTABLE, AND ENFORCED HERE RATHER THAN IN THE UI. Thirteen persisted places key off
+     * this string — `work_items.owner` (indexed), `work_item_comments.author`,
+     * `projects.active_agent`, `file_locks.agent_id`, the conversation file's `agentId`,
+     * `agentIds[]`, `activeAgentId` and its `agentHistories` Record, every message's `agentId`,
+     * and both sides of every handoff marker.
+     *
+     * ⚠️ AND ONE THAT CANNOT BE MIGRATED AT ALL: the literal `$handle` is persisted inside
+     * message PROSE. Mentions are resolved when typed, not when read, so the raw text is what
+     * gets stored. A perfect cascading rename still cannot fix `$arch` in a sentence a user
+     * wrote months ago — and rewriting their words to keep a reference alive is worse than not
+     * renaming.
+     *
+     * The rename path is DUPLICATE, which already excludes handle and face because both must
+     * be unique. Explicit and reversible, where a cascading rename is neither.
      */
     readonly id: string;
     /**
      * Display name shown in UI
      */
-    readonly displayName: string;
+    displayName: string;
     /**
      * Mascot expression for visual differentiation
      */
-    readonly mascot: MascotExpression;
+    mascot: MascotExpression;
     /**
      * Role type
      */
@@ -36,11 +92,11 @@ export declare class TeamAgent {
     /**
      * Optional description
      */
-    readonly description?: string;
+    description?: string;
     /**
      * System prompt addition specific to this agent
      */
-    readonly systemPromptAddition?: string;
+    systemPromptAddition?: string;
     /**
      * Use minimal system prompt - skip all modules
      */
@@ -52,15 +108,15 @@ export declare class TeamAgent {
     /**
      * Tool filter (tool names this agent can use)
      */
-    readonly toolFilter?: string[];
+    toolFilter?: string[];
     /**
      * Tool profile name (for display)
      */
-    readonly toolProfile?: TeamAgentConfig['toolProfile'];
+    toolProfile?: TeamAgentConfig['toolProfile'];
     /**
      * Enabled skills (empty = all skills)
      */
-    readonly enabledSkills?: string[];
+    enabledSkills?: string[];
     /**
      * Auto-approve handoffs from this agent without user confirmation
      */
@@ -122,6 +178,32 @@ export declare class TeamAgent {
      * @param newTier - The new model tier to use
      */
     setModelTier(newTier: ModelTier): void;
+    /**
+     * Serialise the live agent, keep its history, and drop the instance so the next
+     * `initialize()` rebuilds it.
+     *
+     * ⚠️ EXTRACTED so `setModelTier` and `applyUpdate` cannot drift. Two copies of a
+     * history-transfer is exactly the kind of duplication that survives review and then
+     * silently loses a conversation when only one of them is fixed.
+     *
+     * Thinking blocks are stripped: they carry provider-specific signatures (Gemini's
+     * `thought_signature`) that do not transfer across a rebuild.
+     */
+    private stashForRebuild;
+    /**
+     * Apply an edit to this agent in place.
+     *
+     * ⚠️ IN PLACE, NOT A REPLACEMENT INSTANCE. Other structures hold `TeamAgent` references —
+     * swapping the object in the team's map would leave every one of them pointing at a stale
+     * agent, and nothing would report it.
+     *
+     * Returns whether the change requires the underlying agent to be rebuilt. Metadata
+     * (`displayName`, `mascot`, `description`) is read from the roster at render time, so a
+     * rename is retroactive and free; anything that feeds agent CONSTRUCTION is not.
+     */
+    applyUpdate(patch: TeamAgentUpdate): {
+        rebuilt: boolean;
+    };
     /**
      * Initialize the agent with the given factory
      * This allows the team to control agent creation

package/dist/team/team-agent.js

@@ -17,12 +17,66 @@ import { getToolsForProfile, generateToolAwarenessPrompt, generateCoordinatorGui
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
+/**
+ * Did the tool profile get strictly smaller?
+ *
+ * ⚠️ Decided by whether the profile is READ-ONLY, not by counting tools. A profile with more
+ * tools that cannot write is a narrowing in every sense the user cares about, and tool counts
+ * shift whenever the registry grows.
+ */
+export function isNarrowing(before, after) {
+    if (before === after)
+        return false;
+    if (before === undefined || after === undefined)
+        return false;
+    return !READ_ONLY_PROFILES.has(before) && READ_ONLY_PROFILES.has(after);
+}
+/**
+ * The profiles that cannot change files.
+ *
+ * ⚠️ Kept in step with `PROFILE_INFO.isReadOnly` by a test, not by discipline — this module
+ * cannot import tool-config without a cycle.
+ */
+const READ_ONLY_PROFILES = new Set([
+    'read-only',
+    'security',
+    'qa',
+    'architect',
+    'planner',
+    'analyst',
+    'designer',
+]);
+/** Order-insensitive comparison — a reordered skill list is not a change. */
+function sameStrings(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    const x = [...a].sort();
+    const y = [...b].sort();
+    return x.every((v, i) => v === y[i]);
+}
 /**
  * TeamAgent wraps an Agent instance with team-specific metadata
  */
 export class TeamAgent {
     /**
-     * Unique identifier (e.g., 'pm', 'arch', 'qa')
+     * Unique identifier (e.g., 'pm', 'arch', 'qa').
+     *
+     * ⚠️ IMMUTABLE, AND ENFORCED HERE RATHER THAN IN THE UI. Thirteen persisted places key off
+     * this string — `work_items.owner` (indexed), `work_item_comments.author`,
+     * `projects.active_agent`, `file_locks.agent_id`, the conversation file's `agentId`,
+     * `agentIds[]`, `activeAgentId` and its `agentHistories` Record, every message's `agentId`,
+     * and both sides of every handoff marker.
+     *
+     * ⚠️ AND ONE THAT CANNOT BE MIGRATED AT ALL: the literal `$handle` is persisted inside
+     * message PROSE. Mentions are resolved when typed, not when read, so the raw text is what
+     * gets stored. A perfect cascading rename still cannot fix `$arch` in a sentence a user
+     * wrote months ago — and rewriting their words to keep a reference alive is worse than not
+     * renaming.
+     *
+     * The rename path is DUPLICATE, which already excludes handle and face because both must
+     * be unique. Explicit and reversible, where a cascading rename is neither.
      */
     id;
     /**
@@ -154,27 +208,70 @@ export class TeamAgent {
         if (newTier === this._modelTier) {
             return; // No change needed
         }
-        // Store current state if agent is initialized
-        if (this._agent) {
-            const state = this._agent.serialize();
-            // Strip thinking blocks from messages - they contain provider-specific
-            // signatures (e.g., Gemini's thought_signature) that don't transfer
-            // between sessions or model changes
-            state.messages = state.messages.map((msg) => {
-                // Content can be string or ContentBlock[]
-                if (typeof msg.content === 'string') {
-                    return msg;
-                }
-                return {
-                    ...msg,
-                    content: msg.content.filter((block) => block.type !== 'thinking'),
-                };
-            });
-            this.storedState = state;
-            this._agent = null; // Clear agent so it will be reinitialized
-        }
+        this.stashForRebuild();
         this._modelTier = newTier;
     }
+    /**
+     * Serialise the live agent, keep its history, and drop the instance so the next
+     * `initialize()` rebuilds it.
+     *
+     * ⚠️ EXTRACTED so `setModelTier` and `applyUpdate` cannot drift. Two copies of a
+     * history-transfer is exactly the kind of duplication that survives review and then
+     * silently loses a conversation when only one of them is fixed.
+     *
+     * Thinking blocks are stripped: they carry provider-specific signatures (Gemini's
+     * `thought_signature`) that do not transfer across a rebuild.
+     */
+    stashForRebuild() {
+        if (!this._agent)
+            return;
+        const state = this._agent.serialize();
+        state.messages = state.messages.map((msg) => {
+            if (typeof msg.content === 'string')
+                return msg;
+            return {
+                ...msg,
+                content: msg.content.filter((block) => block.type !== 'thinking'),
+            };
+        });
+        this.storedState = state;
+        this._agent = null;
+    }
+    /**
+     * Apply an edit to this agent in place.
+     *
+     * ⚠️ IN PLACE, NOT A REPLACEMENT INSTANCE. Other structures hold `TeamAgent` references —
+     * swapping the object in the team's map would leave every one of them pointing at a stale
+     * agent, and nothing would report it.
+     *
+     * Returns whether the change requires the underlying agent to be rebuilt. Metadata
+     * (`displayName`, `mascot`, `description`) is read from the roster at render time, so a
+     * rename is retroactive and free; anything that feeds agent CONSTRUCTION is not.
+     */
+    applyUpdate(patch) {
+        const needsRebuild = (patch.systemPromptAddition !== undefined &&
+            patch.systemPromptAddition !== this.systemPromptAddition) ||
+            (patch.toolProfile !== undefined && patch.toolProfile !== this.toolProfile) ||
+            (patch.toolFilter !== undefined && !sameStrings(patch.toolFilter, this.toolFilter)) ||
+            (patch.enabledSkills !== undefined && !sameStrings(patch.enabledSkills, this.enabledSkills));
+        if (patch.displayName !== undefined)
+            this.displayName = patch.displayName;
+        if (patch.mascot !== undefined)
+            this.mascot = patch.mascot;
+        if (patch.description !== undefined)
+            this.description = patch.description;
+        if (patch.systemPromptAddition !== undefined)
+            this.systemPromptAddition = patch.systemPromptAddition;
+        if (patch.toolProfile !== undefined)
+            this.toolProfile = patch.toolProfile;
+        if (patch.toolFilter !== undefined)
+            this.toolFilter = patch.toolFilter;
+        if (patch.enabledSkills !== undefined)
+            this.enabledSkills = patch.enabledSkills;
+        if (needsRebuild)
+            this.stashForRebuild();
+        return { rebuilt: needsRebuild };
+    }
     /**
      * Initialize the agent with the given factory
      * This allows the team to control agent creation

package/dist/team/team.d.ts

@@ -14,6 +14,7 @@ import type { ModelTier } from '../models/index.js';
 import { SharedContextManager } from './shared-context.js';
 import { ArtifactStore } from './artifacts.js';
 import type { CustomAgentDefinition } from './custom-agents.js';
+import type { TeamAgentUpdate, AgentUpdateResult } from './team-agent.js';
 import type { ISessionRegistry } from './interfaces.js';
 /**
  * Configuration for creating an AgentTeam
@@ -192,6 +193,20 @@ export declare class AgentTeam {
     /**
      * Remove an agent from the team
      */
+    /**
+     * Edit an existing agent.
+     *
+     * ⚠️ THE FIRST WAY TO CHANGE AN AGENT WITHOUT DELETING IT. Until this existed, altering a
+     * name, instruction, tool profile or skill set meant `removeAgent` + `addAgent`, which
+     * orphans every conversation the agent owned.
+     *
+     * Returns what the caller needs to decide whether to tell anyone:
+     *  - `rebuilt` — the underlying agent was dropped and will rebuild on next use, carrying
+     *    its history across.
+     *  - `toolsNarrowed` — the agent may now touch strictly LESS than it could. See the note
+     *    on the return type: this is the case that needs to reach the conversation.
+     */
+    updateAgent(id: string, patch: TeamAgentUpdate): Promise<AgentUpdateResult>;
     removeAgent(id: string): boolean;
     /**
      * Clear conversation history for all agents in the team

package/dist/team/team.js

@@ -11,6 +11,7 @@ import { TeamAgent } from './team-agent.js';
 import { ROLE_EXPERTISE } from './types.js';
 import { SharedContextManager } from './shared-context.js';
 import { ArtifactStore } from './artifacts.js';
+import { isNarrowing } from './team-agent.js';
 import { resolveAgentIdCollision } from './collision-utils.js';
 /**
  * AgentTeam orchestrates multiple persistent agents
@@ -311,6 +312,50 @@ export class AgentTeam {
     /**
      * Remove an agent from the team
      */
+    /**
+     * Edit an existing agent.
+     *
+     * ⚠️ THE FIRST WAY TO CHANGE AN AGENT WITHOUT DELETING IT. Until this existed, altering a
+     * name, instruction, tool profile or skill set meant `removeAgent` + `addAgent`, which
+     * orphans every conversation the agent owned.
+     *
+     * Returns what the caller needs to decide whether to tell anyone:
+     *  - `rebuilt` — the underlying agent was dropped and will rebuild on next use, carrying
+     *    its history across.
+     *  - `toolsNarrowed` — the agent may now touch strictly LESS than it could. See the note
+     *    on the return type: this is the case that needs to reach the conversation.
+     */
+    async updateAgent(id, patch) {
+        const agent = this.agents.get(id);
+        if (!agent) {
+            throw new Error(`Agent '${id}' not found in team`);
+        }
+        /*
+          ⚠️ Guarded here even though `TeamAgentUpdate` has no `id`. A patch arriving over IPC is
+          a plain object that TypeScript never saw; the immutability decision has to hold against
+          data, not only against callers that compiled.
+        */
+        if ('id' in patch) {
+            throw new Error(`Agent id is immutable — '${id}' cannot be renamed. Duplicate the agent instead: ` +
+                'mention handles are written into stored message text and cannot be migrated.');
+        }
+        const previousProfile = agent.toolProfile;
+        const { rebuilt } = agent.applyUpdate(patch);
+        if (rebuilt) {
+            // Rebuild now rather than lazily, so a failure surfaces at save time.
+            await agent.initialize(this.agentFactory, this._sharedContext);
+        }
+        // displayName/mascot feed the roster injected into every agent's context.
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:updated', agentId: id });
+        return {
+            rebuilt,
+            toolsNarrowed: isNarrowing(previousProfile, agent.toolProfile),
+            previousProfile,
+            newProfile: agent.toolProfile,
+        };
+    }
     removeAgent(id) {
         if (id === 'default') {
             throw new Error('Cannot remove the default agent');

package/dist/team/tool-config.js

@@ -297,6 +297,9 @@ export const TOOL_GROUPS = {
             'canvas_validate',
             'canvas_screenshot',
             'canvas_guide',
+            'canvas_asset_add',
+            'canvas_asset_list',
+            'canvas_asset_delete',
         ],
         readOnly: false,
         tier: 'meta',

package/dist/team/types.d.ts

@@ -211,7 +211,7 @@ export interface SerializedTeam {
 /**
  * Event types for team operations
  */
-export type TeamEventType = 'agent:added' | 'agent:removed' | 'agent:switched' | 'agent:switch_warning' | 'agent:collision' | 'agent:message' | 'team:checkpoint' | 'team:restored' | 'team:reset';
+export type TeamEventType = 'agent:added' | 'agent:updated' | 'agent:removed' | 'agent:switched' | 'agent:switch_warning' | 'agent:collision' | 'agent:message' | 'team:checkpoint' | 'team:restored' | 'team:reset';
 /**
  * Team event payload
  */

package/package.json

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