@compilr-dev/sdk 0.23.1 → 0.24.0

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

@@ -68,6 +68,8 @@ export interface TeamAgentUpdate {
     toolProfile?: TeamAgentConfig['toolProfile'];
     toolFilter?: string[];
     enabledSkills?: string[];
+    /** Which MCP servers this agent may reach. See `TeamAgent.mcpServers`. */
+    mcpServers?: string[];
 }
 /** What an edit did, and whether anyone needs telling. */
 export interface AgentUpdateResult {
@@ -185,6 +187,15 @@ export declare class TeamAgent {
      * from the profile name alone.
      */
     customGroups?: string[];
+    /**
+     * MCP servers this agent may reach. `undefined` = a pre-grants agent, which reaches all;
+     * `[]` = granted nothing. See `TeamAgentConfig.mcpServers`.
+     *
+     * The SDK holds the grant; the HOST enforces it, because the host owns the MCP connection and
+     * decides which tools an agent is built with. `grantsMcpServer()` is the shared predicate so
+     * the two cannot disagree about what `undefined` means.
+     */
+    mcpServers?: string[];
     /**
      * Enabled skills (empty = all skills)
      */
@@ -272,6 +283,37 @@ export declare class TeamAgent {
      * `thought_signature`) that do not transfer across a rebuild.
      */
     private stashForRebuild;
+    /**
+     * A turn is in flight: the host has called `run()`/`stream()` and is awaiting it.
+     *
+     * ⚠️ HOSTS MUST BRACKET EVERY RUN, IN A `finally`. `TeamAgent` does not own the run call —
+     * the host holds the unwrapped `Agent` — so it cannot observe this for itself.
+     */
+    private turnStartedAt;
+    /**
+     * How long a turn may be in flight before this stops believing the host.
+     *
+     * ⚠️ A FLAG THAT ONLY EVER GETS SET IS WORSE THAN THE BUG IT GUARDS. A host that throws past
+     * its `endTurn()` would block every edit to that agent for the life of the process, with no
+     * way back short of a restart. Going stale bounds that to one window; the edit that slips
+     * through after it is the same edit that would have been allowed before this guard existed.
+     */
+    private static readonly TURN_STALE_AFTER_MS;
+    /**
+     * Whether this agent may reach an MCP server.
+     *
+     * ⚠️ THE ONE PLACE `undefined` IS INTERPRETED. Hosts filter the tools they build an agent
+     * with, so each one would otherwise re-decide what "never asked" means — and a host that
+     * read it as "deny" would silently strip reach from every agent created before grants
+     * existed, which is the migration we explicitly chose not to do.
+     */
+    grantsMcpServer(server: string): boolean;
+    /** Mark the start of a turn. Pair with `endTurn()` in a `finally`. */
+    beginTurn(): void;
+    /** Mark the end of a turn, however it ended — completed, aborted or thrown. */
+    endTurn(): void;
+    /** Whether a turn is in flight and recent enough to still be believed. */
+    get isTurnInFlight(): boolean;
     /**
      * Apply an edit to this agent in place.
      *
@@ -312,7 +354,20 @@ export declare class TeamAgent {
      * @param agentFactory Factory function to create the agent
      * @param sharedContext Optional shared context to inject into system prompt
      */
-    initialize(agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier) => Promise<Agent>, sharedContext?: SharedContextManager): Promise<void>;
+    initialize(agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier, 
+    /**
+     * Which agent is being built.
+     *
+     * ⚠️ ADDED BECAUSE THE FACTORY COULD NOT TELL ITS AGENTS APART. Per-agent MCP grants are
+     * enforced by the HOST — it owns the connection and decides which tools an agent is
+     * constructed with — and it could not, because every parameter here described the
+     * configuration and none identified the agent. Desktop's episode recorder had already
+     * worked around the same gap by recording every team agent under the literal id
+     * 'team-agent'.
+     *
+     * Optional, so a host that ignores it behaves exactly as before.
+     */
+    teamAgent?: TeamAgent) => Promise<Agent>, sharedContext?: SharedContextManager): Promise<void>;
     /**
      * Set the agent instance directly
      * Used for the default agent when an agent is created before the team

package/dist/team/team-agent.js

@@ -203,6 +203,15 @@ export class TeamAgent {
      * from the profile name alone.
      */
     customGroups;
+    /**
+     * MCP servers this agent may reach. `undefined` = a pre-grants agent, which reaches all;
+     * `[]` = granted nothing. See `TeamAgentConfig.mcpServers`.
+     *
+     * The SDK holds the grant; the HOST enforces it, because the host owns the MCP connection and
+     * decides which tools an agent is built with. `grantsMcpServer()` is the shared predicate so
+     * the two cannot disagree about what `undefined` means.
+     */
+    mcpServers;
     /**
      * Enabled skills (empty = all skills)
      */
@@ -261,6 +270,7 @@ export class TeamAgent {
         this.toolFilter = config.toolFilter;
         this.toolProfile = config.toolProfile;
         this.customGroups = config.customGroups;
+        this.mcpServers = config.mcpServers;
         this.enabledSkills = config.enabledSkills;
         this.personality = config.personality;
         this.autoApproveHandoff = config.autoApproveHandoff;
@@ -337,6 +347,47 @@ export class TeamAgent {
         this.storedState = state;
         this._agent = null;
     }
+    /**
+     * A turn is in flight: the host has called `run()`/`stream()` and is awaiting it.
+     *
+     * ⚠️ HOSTS MUST BRACKET EVERY RUN, IN A `finally`. `TeamAgent` does not own the run call —
+     * the host holds the unwrapped `Agent` — so it cannot observe this for itself.
+     */
+    turnStartedAt = null;
+    /**
+     * How long a turn may be in flight before this stops believing the host.
+     *
+     * ⚠️ A FLAG THAT ONLY EVER GETS SET IS WORSE THAN THE BUG IT GUARDS. A host that throws past
+     * its `endTurn()` would block every edit to that agent for the life of the process, with no
+     * way back short of a restart. Going stale bounds that to one window; the edit that slips
+     * through after it is the same edit that would have been allowed before this guard existed.
+     */
+    static TURN_STALE_AFTER_MS = 10 * 60 * 1000;
+    /**
+     * Whether this agent may reach an MCP server.
+     *
+     * ⚠️ THE ONE PLACE `undefined` IS INTERPRETED. Hosts filter the tools they build an agent
+     * with, so each one would otherwise re-decide what "never asked" means — and a host that
+     * read it as "deny" would silently strip reach from every agent created before grants
+     * existed, which is the migration we explicitly chose not to do.
+     */
+    grantsMcpServer(server) {
+        return this.mcpServers === undefined || this.mcpServers.includes(server);
+    }
+    /** Mark the start of a turn. Pair with `endTurn()` in a `finally`. */
+    beginTurn() {
+        this.turnStartedAt = Date.now();
+    }
+    /** Mark the end of a turn, however it ended — completed, aborted or thrown. */
+    endTurn() {
+        this.turnStartedAt = null;
+    }
+    /** Whether a turn is in flight and recent enough to still be believed. */
+    get isTurnInFlight() {
+        if (this.turnStartedAt === null)
+            return false;
+        return Date.now() - this.turnStartedAt < TeamAgent.TURN_STALE_AFTER_MS;
+    }
     /**
      * Apply an edit to this agent in place.
      *
@@ -354,12 +405,33 @@ export class TeamAgent {
             (patch.personality !== undefined && patch.personality !== this.personality) ||
             (patch.toolProfile !== undefined && patch.toolProfile !== this.toolProfile) ||
             (patch.toolFilter !== undefined && !sameStrings(patch.toolFilter, this.toolFilter)) ||
-            (patch.enabledSkills !== undefined && !sameStrings(patch.enabledSkills, this.enabledSkills));
+            (patch.enabledSkills !== undefined &&
+                !sameStrings(patch.enabledSkills, this.enabledSkills)) ||
+            (patch.mcpServers !== undefined && !sameStrings(patch.mcpServers, this.mcpServers));
         /*
           Delegated: `setModelTier` no-ops when the tier is unchanged and stashes for rebuild
           when it is not. Its `rebuilt` contribution is folded in below.
         */
         const tierChanged = patch.modelTier !== undefined && patch.modelTier !== this._modelTier;
+        /*
+          ⚠️ REFUSED MID-TURN, BEFORE ANYTHING IS MUTATED. A rebuild snapshots the history with
+          `serialize()` and drops the instance — but the in-flight `run()` holds its own reference
+          and finishes anyway, appending to an agent nobody will read again. Measured: the user
+          watches a reply stream in, and the rebuilt agent is handed the snapshot from BEFORE it,
+          with no memory of having said it.
+    
+          Not a broken conversation — `setHistory` repairs tool pairing, so nothing 400s. It is
+          worse than that: the agent silently forgets a turn the user just watched, and the next
+          thing it says is built on a history the user can see is wrong.
+    
+          Only rebuilding edits are refused. A rename or a new face is read from the roster at
+          render time and cannot tear anything, so those still apply mid-turn.
+        */
+        if ((needsRebuild || tierChanged) && this.isTurnInFlight) {
+            throw new Error(`Agent '${this.id}' is mid-reply. Changing its prompt, model, tools or skills rebuilds ` +
+                `it and would drop the turn it is in the middle of — wait for the reply to finish, ` +
+                `or stop it, then save.`);
+        }
         if (patch.modelTier !== undefined)
             this.setModelTier(patch.modelTier);
         if (patch.displayName !== undefined)
@@ -372,6 +444,8 @@ export class TeamAgent {
             this.systemPromptAddition = patch.systemPromptAddition;
         if (patch.personality !== undefined)
             this.personality = patch.personality;
+        if (patch.mcpServers !== undefined)
+            this.mcpServers = patch.mcpServers;
         /*
           ⚠️ THE PROFILE IS A LABEL; `toolFilter` IS THE ENFORCEMENT. `initialize()` passes
           `toolFilter` to the factory and never looks at `toolProfile`, so setting the profile
@@ -501,7 +575,8 @@ export class TeamAgent {
             }
         }
         this._agent = await agentFactory(this.agentConfig, finalSystemPromptAddition || undefined, this.useMinimalSystemPrompt, this.noTools, this.toolFilter, // Pass tool filter to factory
-        this._modelTier // Pass model tier to factory
+        this._modelTier, // Pass model tier to factory
+        this // So the host can honour this agent's MCP grants and name it in logs
         );
         // Set the team roster as a pin (dynamically re-injected on every LLM call).
         // This ensures roster updates (agent added/removed) are always visible.
@@ -682,6 +757,7 @@ export class TeamAgent {
             toolFilter: this.toolFilter,
             toolProfile: this.toolProfile,
             customGroups: this.customGroups,
+            mcpServers: this.mcpServers,
             enabledSkills: this.enabledSkills,
             modelTier: this.modelTier,
             autoApproveHandoff: this.autoApproveHandoff,
@@ -738,6 +814,7 @@ export class TeamAgent {
             toolFilter,
             toolProfile: data.toolProfile,
             customGroups: data.customGroups,
+            mcpServers: data.mcpServers,
             enabledSkills: data.enabledSkills,
             modelTier: data.modelTier,
             autoApproveHandoff: data.autoApproveHandoff,

package/dist/team/team.d.ts

@@ -34,7 +34,9 @@ export interface AgentTeamConfig {
      * @param toolFilter - Limit which tools this agent can use
      * @param modelTier - Model tier for this agent (fast/balanced/powerful)
      */
-    agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier) => Promise<Agent>;
+    agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier, 
+    /** Which agent is being built — see TeamAgent.initialize. */
+    teamAgent?: TeamAgent) => Promise<Agent>;
     /**
      * Initial agents to add to the team (optional)
      * If not provided, starts with just the default agent

package/dist/team/types.d.ts

@@ -137,6 +137,16 @@ export interface TeamAgentConfig {
     toolProfile?: ToolProfile;
     /** Groups behind a `custom` profile — see TeamAgent.customGroups. */
     customGroups?: string[];
+    /**
+     * MCP servers this agent may reach, by server name.
+     *
+     * ⚠️ `undefined` AND `[]` MEAN DIFFERENT THINGS, DELIBERATELY. `undefined` is "never asked" —
+     * every agent serialized before per-agent grants existed, which reached every server, and
+     * still does. `[]` is "asked, and granted nothing", which is what a newly created agent gets.
+     * Collapsing them would either strip reach from agents that depend on it or hand every new
+     * agent the whole machine.
+     */
+    mcpServers?: string[];
     /**
      * Enabled skills for this agent
      * Empty array means all skills, non-empty means filtered
@@ -176,6 +186,8 @@ export interface SerializedTeamAgent {
     toolFilter?: string[];
     toolProfile?: ToolProfile;
     customGroups?: string[];
+    /** See TeamAgentConfig.mcpServers — undefined means a pre-grants agent, which reaches all. */
+    mcpServers?: string[];
     enabledSkills?: string[];
     modelTier?: ModelTier;
     autoApproveHandoff?: boolean;

package/package.json

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