@compilr-dev/sdk 0.23.2 → 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)
      */
@@ -288,6 +299,15 @@ export declare class TeamAgent {
      * 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. */
@@ -334,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;
@@ -353,6 +363,17 @@ export class TeamAgent {
      * 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();
@@ -384,7 +405,9 @@ 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.
@@ -421,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
@@ -550,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.
@@ -731,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,
@@ -787,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.2",
+  "version": "0.24.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",