@compilr-dev/sdk 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTr
 export type { AgentTeamConfig, TeamAgentConfig, TeamAgentUpdate, AgentUpdateResult, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopSkillDef, PlanSubmitInfo, PlanSubmitResult, PlanModeExitInfo, PlanModeCallbacks, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
 export type { AgentRole, RoleMetadata, ToolProfile, MascotExpression, BackgroundSessionInfo, SerializedTeam, SerializedTeamAgent, TeamMetadata, TeamEvent, TeamEventType, TeamEventHandler, Artifact, ArtifactType as TeamArtifactType, ArtifactSummary as TeamArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, ParsedMention, ParsedInput, ResolvedMention, ResolveOptions, ResolutionSource, Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, HandoffResult, HandoffToolConfig, HandoffIntent, HandoffValidationResult, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, ConsultInput, ConsultResult, ConsultToolConfig, NormalizedRole, SkillToolRequirement, } from './team/index.js';
 export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './team/index.js';
-export { getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, assignMascot, generateCustomAgentSystemPrompt, mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, buildContextMap, findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, suggestOwner, suggestOwners, matchesAgentExpertise, wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, resolveAgentIdCollision, setActiveSharedContext, getActiveSharedContext, recordTeamActivity, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
+export { getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, assignMascot, generateCustomAgentSystemPrompt, mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, buildContextMap, findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, suggestOwner, suggestOwners, matchesAgentExpertise, wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, resolveAgentIdCollision, setActiveSharedContext, getActiveSharedContext, recordTeamActivity, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, macroToolGap, macroToolGapPreamble, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
 export { codingPreset, readOnlyPreset, resolvePreset } from './presets/index.js';
 export type { Preset } from './presets/index.js';
 export type { AnyTool } from './presets/types.js';

package/dist/index.js

@@ -67,7 +67,7 @@ resolveAgentIdCollision,
 // Activity
 setActiveSharedContext, getActiveSharedContext, recordTeamActivity, 
 // Skills
-getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
+getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, macroToolGap, macroToolGapPreamble, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
 // =============================================================================
 // Presets
 // =============================================================================

package/dist/skills/resolver.d.ts

@@ -62,10 +62,15 @@ export declare function resolveSkillsForAgent(skills: CustomSkill[], context: Sk
  * than once. Every judgement lives here: which fields of the agent matter, and what an absent
  * allowlist means.
  *
- * ⚠️ `enabledSkills: []` IS NOT `undefined`, exactly as with MCP grants. `undefined` is "never
- * asked" — every agent created before skills were choosable, which must keep reaching everything
- * eligible. `[]` is "asked, and granted nothing". Collapsing them either strips capability from
- * working agents or hands new ones the lot.
+ * ⚠️ READS `grantedSkills`, NOT `enabledSkills`. Those are different fields for different things.
+ * `enabledSkills` holds COMMANDS — the 13 its picker offers are `code-review`, `debug`, `design`,
+ * `prd` and friends, all slash commands a user types — and 0.25.0 wired Skills enforcement onto
+ * it, so ticking "Code Review" wrote a name no installed skill has and the agent silently got
+ * zero skills.
+ *
+ * `grantedSkills` follows the MCP contract: `undefined` = never asked, reaches everything
+ * eligible; `[]` = granted nothing. That reading is legitimate here precisely because the field
+ * is new and nothing has a prior meaning.
  *
  * @param pool  every skill installed for this machine/project, unfiltered
  * @param agent the agent being built — role, id and its allowlist come from here
@@ -74,7 +79,8 @@ export declare function resolveSkillsForAgent(skills: CustomSkill[], context: Sk
 export declare function resolveSkillsForTeamAgent(pool: CustomSkill[], agent: {
     id: string;
     role?: string;
-    enabledSkills?: readonly string[];
+    /** Skills this agent may choose. NOT `enabledSkills`, which holds Commands. */
+    grantedSkills?: readonly string[];
 }, opts?: {
     projectType?: string;
     toolNames?: readonly string[];

package/dist/skills/resolver.js

@@ -46,6 +46,13 @@ export function resolveLayeredSkills(layers) {
  */
 export function resolveSkillsForAgent(skills, context) {
     const toolSet = context.toolNames instanceof Set ? context.toolNames : new Set(context.toolNames ?? []);
+    /*
+      ⚠️ THIS SET COMES FROM `grantedSkills`, WHICH IS NEW — so `[]` correctly means "granted
+      nothing", the MCP contract. It does NOT come from `enabledSkills`, which holds Commands and
+      has always documented empty as "all skills"; 0.25.0 conflated the two and every custom agent
+      silently lost its skills. `resolveSkillsForTeamAgent` is the only caller that maps a field
+      onto this context, which is where that distinction is kept.
+    */
     const allowlist = context.enabledSkills ? new Set(context.enabledSkills) : null;
     return skills.filter((skill) => {
         if (skill.enabled === false)
@@ -87,10 +94,15 @@ export function resolveSkillsForAgent(skills, context) {
  * than once. Every judgement lives here: which fields of the agent matter, and what an absent
  * allowlist means.
  *
- * ⚠️ `enabledSkills: []` IS NOT `undefined`, exactly as with MCP grants. `undefined` is "never
- * asked" — every agent created before skills were choosable, which must keep reaching everything
- * eligible. `[]` is "asked, and granted nothing". Collapsing them either strips capability from
- * working agents or hands new ones the lot.
+ * ⚠️ READS `grantedSkills`, NOT `enabledSkills`. Those are different fields for different things.
+ * `enabledSkills` holds COMMANDS — the 13 its picker offers are `code-review`, `debug`, `design`,
+ * `prd` and friends, all slash commands a user types — and 0.25.0 wired Skills enforcement onto
+ * it, so ticking "Code Review" wrote a name no installed skill has and the agent silently got
+ * zero skills.
+ *
+ * `grantedSkills` follows the MCP contract: `undefined` = never asked, reaches everything
+ * eligible; `[]` = granted nothing. That reading is legitimate here precisely because the field
+ * is new and nothing has a prior meaning.
  *
  * @param pool  every skill installed for this machine/project, unfiltered
  * @param agent the agent being built — role, id and its allowlist come from here
@@ -100,7 +112,7 @@ export function resolveSkillsForTeamAgent(pool, agent, opts = {}) {
     return resolveSkillsForAgent(pool, {
         role: agent.role,
         agentId: agent.id,
-        enabledSkills: agent.enabledSkills,
+        enabledSkills: agent.grantedSkills,
         projectType: opts.projectType,
         toolNames: opts.toolNames,
     });

package/dist/team/index.d.ts

@@ -7,6 +7,8 @@
 export { AgentTeam } from './team.js';
 export type { AgentTeamConfig } from './team.js';
 export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
+export { macroToolGap, macroToolGapPreamble } from './macro-tool-gap.js';
+export type { MacroToolGap } from './macro-tool-gap.js';
 export { mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX } from './mcp-servers.js';
 export type { TeamAgentUpdate, AgentUpdateResult } from './team-agent.js';
 export { SharedContextManager } from './shared-context.js';

package/dist/team/index.js

@@ -7,6 +7,7 @@
 // Core classes
 export { AgentTeam } from './team.js';
 export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
+export { macroToolGap, macroToolGapPreamble } from './macro-tool-gap.js';
 export { mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX } from './mcp-servers.js';
 export { SharedContextManager } from './shared-context.js';
 export { ArtifactStore } from './artifacts.js';

package/dist/team/macro-tool-gap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Telling an agent, up front, that a macro needs tools it does not have.
+ *
+ * ⚠️ A MACRO'S TEXT ASSUMES TOOLS, AND NOTHING CHECKED. `/design` instructs the agent to use
+ * `ask_user` and `workitem_add`; sent to an agent that cannot reach those, it announces it is
+ * starting a requirements session and then fails partway, having already promised the user
+ * something it cannot deliver. The failure surfaces as the agent being broken rather than as a
+ * mismatch anyone can act on.
+ *
+ * The data for this has existed all along — `SKILL_REQUIREMENTS` carries `required`, `optional`
+ * and a written `reason` per macro, and `checkSkillCompatibility` does the comparison. Between
+ * them they had exactly one caller: a display hint in the CLI's agent wizard.
+ *
+ * ⚠️ THE WARNING GOES TO THE AGENT, NOT THE USER. A host-side dialog stops the user at a moment
+ * they cannot resolve — they do not know which tools `/design` needs or which teammate has them.
+ * The agent does know, once told, and is where the user is already looking: it can explain in one
+ * sentence and suggest the handoff.
+ */
+export interface MacroToolGap {
+    /** Tools the macro cannot work without. Non-empty whenever a gap is reported. */
+    missingRequired: string[];
+    /** Tools the macro uses when present. Reported so the agent can say what it will skip. */
+    missingOptional: string[];
+    /** The macro's own stated reason for needing them, from SKILL_REQUIREMENTS. */
+    reason: string;
+}
+/**
+ * What this macro needs and this agent lacks, or `null` when there is nothing to say.
+ *
+ * `null` for an unknown macro is deliberate: only 13 have declared requirements, so silence means
+ * "not described", never "verified fine". Warning on an undeclared macro would train people to
+ * ignore the warning.
+ */
+export declare function macroToolGap(macroName: string, availableTools: Set<string> | readonly string[]): MacroToolGap | null;
+/**
+ * A preamble to prepend to the macro's message, addressed to the agent.
+ *
+ * ⚠️ IT TELLS THE AGENT WHAT TO DO, NOT JUST WHAT IS WRONG. "You lack write_file" invites it to
+ * try anyway and fail at the first call. Naming the consequence and the recovery — say so, offer
+ * the handoff — is what turns a broken turn into a useful one.
+ */
+export declare function macroToolGapPreamble(macroName: string, gap: MacroToolGap): string;

package/dist/team/macro-tool-gap.js

@@ -0,0 +1,69 @@
+/**
+ * Telling an agent, up front, that a macro needs tools it does not have.
+ *
+ * ⚠️ A MACRO'S TEXT ASSUMES TOOLS, AND NOTHING CHECKED. `/design` instructs the agent to use
+ * `ask_user` and `workitem_add`; sent to an agent that cannot reach those, it announces it is
+ * starting a requirements session and then fails partway, having already promised the user
+ * something it cannot deliver. The failure surfaces as the agent being broken rather than as a
+ * mismatch anyone can act on.
+ *
+ * The data for this has existed all along — `SKILL_REQUIREMENTS` carries `required`, `optional`
+ * and a written `reason` per macro, and `checkSkillCompatibility` does the comparison. Between
+ * them they had exactly one caller: a display hint in the CLI's agent wizard.
+ *
+ * ⚠️ THE WARNING GOES TO THE AGENT, NOT THE USER. A host-side dialog stops the user at a moment
+ * they cannot resolve — they do not know which tools `/design` needs or which teammate has them.
+ * The agent does know, once told, and is where the user is already looking: it can explain in one
+ * sentence and suggest the handoff.
+ */
+import { SKILL_REQUIREMENTS, checkSkillCompatibility } from './skill-requirements.js';
+/**
+ * What this macro needs and this agent lacks, or `null` when there is nothing to say.
+ *
+ * `null` for an unknown macro is deliberate: only 13 have declared requirements, so silence means
+ * "not described", never "verified fine". Warning on an undeclared macro would train people to
+ * ignore the warning.
+ */
+export function macroToolGap(macroName, availableTools) {
+    if (!(macroName in SKILL_REQUIREMENTS))
+        return null;
+    const { missingRequired, missingOptional } = checkSkillCompatibility(macroName, [
+        ...availableTools,
+    ]);
+    // Optional tools alone are not worth interrupting for — the macro still works without them.
+    if (missingRequired.length === 0)
+        return null;
+    return {
+        missingRequired,
+        missingOptional,
+        // Every entry carries one; the fallback exists because the index signature cannot say so.
+        reason: SKILL_REQUIREMENTS[macroName].reason ?? 'carry out this workflow',
+    };
+}
+/**
+ * A preamble to prepend to the macro's message, addressed to the agent.
+ *
+ * ⚠️ IT TELLS THE AGENT WHAT TO DO, NOT JUST WHAT IS WRONG. "You lack write_file" invites it to
+ * try anyway and fail at the first call. Naming the consequence and the recovery — say so, offer
+ * the handoff — is what turns a broken turn into a useful one.
+ */
+export function macroToolGapPreamble(macroName, gap) {
+    const missing = gap.missingRequired.join(', ');
+    const alsoMissing = gap.missingOptional.length > 0
+        ? ` It also uses ${gap.missingOptional.join(', ')}, which you do not have.`
+        : '';
+    /*
+      The stored reasons are written as "Needs to gather requirements and create backlog", so
+      splicing one in after "needs them to" reads "needs them to: Needs to gather…". Strip the
+      lead-in rather than rewrite 13 table entries whose phrasing is fine on its own.
+    */
+    const purpose = gap.reason.replace(/^\s*needs?\s+to\s+/i, '').replace(/\.$/, '');
+    return [
+        `[System] The /${macroName} workflow below needs tools you do not have: ${missing}.`,
+        `It needs them to ${purpose}.${alsoMissing}`,
+        '',
+        'Do NOT start the workflow and fail partway. Tell the user in one or two sentences what you ' +
+            'cannot do and why, and if a teammate has those tools, suggest handing off to them. ' +
+            'If part of the workflow is still useful without those tools, say which part and offer it.',
+    ].join('\n');
+}

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

@@ -70,6 +70,8 @@ export interface TeamAgentUpdate {
     enabledSkills?: string[];
     /** Which MCP servers this agent may reach. See `TeamAgent.mcpServers`. */
     mcpServers?: string[];
+    /** Which Skills this agent may choose. See `TeamAgent.grantedSkills`. */
+    grantedSkills?: string[];
 }
 /** What an edit did, and whether anyone needs telling. */
 export interface AgentUpdateResult {
@@ -187,6 +189,18 @@ export declare class TeamAgent {
      * from the profile name alone.
      */
     customGroups?: string[];
+    /**
+     * Skills this agent may CHOOSE. `undefined` = never asked, reaches everything eligible;
+     * `[]` = granted nothing. Same contract as `mcpServers`.
+     *
+     * ⚠️ NOT `enabledSkills`, WHICH IS A DIFFERENT FIELD FOR A DIFFERENT THING. That one holds
+     * COMMANDS — the 13 names its picker offers are `code-review`, `debug`, `design`, `prd` and
+     * friends, all slash commands a user types. 0.25.0 wired Skills enforcement onto it and
+     * produced a live hazard: ticking "Code Review" wrote a name no installed skill has, so the
+     * agent silently got zero skills. The MCP-style reading is legitimate HERE only because this
+     * field is new and nothing has a prior meaning.
+     */
+    grantedSkills?: string[];
     /**
      * MCP servers this agent may reach. `undefined` = a pre-grants agent, which reaches all;
      * `[]` = granted nothing. See `TeamAgentConfig.mcpServers`.

package/dist/team/team-agent.js

@@ -203,6 +203,18 @@ export class TeamAgent {
      * from the profile name alone.
      */
     customGroups;
+    /**
+     * Skills this agent may CHOOSE. `undefined` = never asked, reaches everything eligible;
+     * `[]` = granted nothing. Same contract as `mcpServers`.
+     *
+     * ⚠️ NOT `enabledSkills`, WHICH IS A DIFFERENT FIELD FOR A DIFFERENT THING. That one holds
+     * COMMANDS — the 13 names its picker offers are `code-review`, `debug`, `design`, `prd` and
+     * friends, all slash commands a user types. 0.25.0 wired Skills enforcement onto it and
+     * produced a live hazard: ticking "Code Review" wrote a name no installed skill has, so the
+     * agent silently got zero skills. The MCP-style reading is legitimate HERE only because this
+     * field is new and nothing has a prior meaning.
+     */
+    grantedSkills;
     /**
      * MCP servers this agent may reach. `undefined` = a pre-grants agent, which reaches all;
      * `[]` = granted nothing. See `TeamAgentConfig.mcpServers`.
@@ -271,6 +283,7 @@ export class TeamAgent {
         this.toolProfile = config.toolProfile;
         this.customGroups = config.customGroups;
         this.mcpServers = config.mcpServers;
+        this.grantedSkills = config.grantedSkills;
         this.enabledSkills = config.enabledSkills;
         this.personality = config.personality;
         this.autoApproveHandoff = config.autoApproveHandoff;
@@ -407,7 +420,8 @@ export class TeamAgent {
             (patch.toolFilter !== undefined && !sameStrings(patch.toolFilter, this.toolFilter)) ||
             (patch.enabledSkills !== undefined &&
                 !sameStrings(patch.enabledSkills, this.enabledSkills)) ||
-            (patch.mcpServers !== undefined && !sameStrings(patch.mcpServers, this.mcpServers));
+            (patch.mcpServers !== undefined && !sameStrings(patch.mcpServers, this.mcpServers)) ||
+            (patch.grantedSkills !== undefined && !sameStrings(patch.grantedSkills, this.grantedSkills));
         /*
           Delegated: `setModelTier` no-ops when the tier is unchanged and stashes for rebuild
           when it is not. Its `rebuilt` contribution is folded in below.
@@ -446,6 +460,8 @@ export class TeamAgent {
             this.personality = patch.personality;
         if (patch.mcpServers !== undefined)
             this.mcpServers = patch.mcpServers;
+        if (patch.grantedSkills !== undefined)
+            this.grantedSkills = patch.grantedSkills;
         /*
           ⚠️ THE PROFILE IS A LABEL; `toolFilter` IS THE ENFORCEMENT. `initialize()` passes
           `toolFilter` to the factory and never looks at `toolProfile`, so setting the profile
@@ -758,6 +774,7 @@ export class TeamAgent {
             toolProfile: this.toolProfile,
             customGroups: this.customGroups,
             mcpServers: this.mcpServers,
+            grantedSkills: this.grantedSkills,
             enabledSkills: this.enabledSkills,
             modelTier: this.modelTier,
             autoApproveHandoff: this.autoApproveHandoff,
@@ -815,6 +832,7 @@ export class TeamAgent {
             toolProfile: data.toolProfile,
             customGroups: data.customGroups,
             mcpServers: data.mcpServers,
+            grantedSkills: data.grantedSkills,
             enabledSkills: data.enabledSkills,
             modelTier: data.modelTier,
             autoApproveHandoff: data.autoApproveHandoff,

package/dist/team/types.d.ts

@@ -147,6 +147,8 @@ export interface TeamAgentConfig {
      * agent the whole machine.
      */
     mcpServers?: string[];
+    /** Skills this agent may choose — see TeamAgent.grantedSkills. Not `enabledSkills`. */
+    grantedSkills?: string[];
     /**
      * Enabled skills for this agent
      * Empty array means all skills, non-empty means filtered
@@ -188,6 +190,8 @@ export interface SerializedTeamAgent {
     customGroups?: string[];
     /** See TeamAgentConfig.mcpServers — undefined means a pre-grants agent, which reaches all. */
     mcpServers?: string[];
+    /** Skills this agent may choose — see TeamAgent.grantedSkills. Not `enabledSkills`. */
+    grantedSkills?: string[];
     enabledSkills?: string[];
     modelTier?: ModelTier;
     autoApproveHandoff?: boolean;

package/package.json

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