@compilr-dev/sdk 0.20.1 → 0.20.3

package/dist/index.d.ts

@@ -35,7 +35,7 @@
  */
 export { createCompilrAgent } from './agent.js';
 export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, CapabilitiesConfig, } from './config.js';
-export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, lostWriteAccess, } from './team/index.js';
 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';

package/dist/index.js

@@ -41,7 +41,7 @@ export { createCompilrAgent } from './agent.js';
 // Multi-Agent Team Orchestration
 // =============================================================================
 // Core classes
-export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, lostWriteAccess, } from './team/index.js';
 // Constants
 export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, 
 // Plan mode

package/dist/team/index.d.ts

@@ -6,7 +6,7 @@
  */
 export { AgentTeam } from './team.js';
 export type { AgentTeamConfig } from './team.js';
-export { TeamAgent, isNarrowing } from './team-agent.js';
+export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
 export type { TeamAgentUpdate, AgentUpdateResult } from './team-agent.js';
 export { SharedContextManager } from './shared-context.js';
 export type { SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, } from './shared-context.js';

package/dist/team/index.js

@@ -6,7 +6,7 @@
  */
 // Core classes
 export { AgentTeam } from './team.js';
-export { TeamAgent, isNarrowing } from './team-agent.js';
+export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
 export { SharedContextManager } from './shared-context.js';
 export { ArtifactStore } from './artifacts.js';
 export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS } from './types.js';

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

@@ -49,17 +49,43 @@ export interface AgentUpdateResult {
      * ability to write files is worth more than the row it costs.
      */
     toolsNarrowed: boolean;
+    /**
+     * ⚠️ NARROWER THAN `toolsNarrowed`, and the host needs both. "Fewer tools" and "cannot
+     * write any more" are different facts; a transcript saying "it can no longer change files"
+     * when six tools were dropped is a false statement in the record.
+     */
+    lostWriteAccess: boolean;
     previousProfile?: TeamAgentConfig['toolProfile'];
     newProfile?: TeamAgentConfig['toolProfile'];
 }
 /**
- * Did the tool profile get strictly smaller?
+ * Did the agent's reach get strictly smaller?
+ *
+ * ⚠️ TWO TESTS, NOT ONE, and the first version had only half of the first.
+ *
+ * Losing the ability to WRITE is the narrowing that matters most, so a move into a read-only
+ * profile counts however the tool counts land. But it is not the only one: `full` → `custom`
+ * with no groups is total tool removal — the largest narrowing there is — and neither profile
+ * is read-only, so a read-only test alone called it no change at all.
  *
- * ⚠️ 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.
+ * ⚠️ `undefined` IS NOT "UNKNOWN". `initialize` passes `toolFilter` straight to the factory,
+ * and an absent filter means NO filter — every tool. So `undefined` → `read-only` is the
+ * maximal narrowing, and the original returned false for it. My own test asserted exactly
+ * that under the name "says nothing when either side is unknown", which is how it survived:
+ * the suite encoded the defect as intended behaviour.
  */
 export declare function isNarrowing(before: TeamAgentConfig['toolProfile'], after: TeamAgentConfig['toolProfile']): boolean;
+/**
+ * Did the agent specifically lose the ability to change files?
+ *
+ * ⚠️ A NARROWER QUESTION THAN `isNarrowing`, and the host needs both. "Fewer tools" and
+ * "cannot write any more" are different facts, and a notice that says "it can no longer
+ * change files" when the agent merely dropped six tools is a false statement in the
+ * transcript — exactly the class of error this whole review found.
+ */
+export declare function lostWriteAccess(before: TeamAgentConfig['toolProfile'], after: TeamAgentConfig['toolProfile']): boolean;
+/** Is this a profile the registry actually knows? Used to refuse bad IPC data. */
+export declare function isKnownProfile(p: unknown): p is NonNullable<TeamAgentConfig['toolProfile']>;
 /**
  * TeamAgent wraps an Agent instance with team-specific metadata
  */

package/dist/team/team-agent.js

@@ -10,7 +10,7 @@
 import { ROLE_METADATA } from './types.js';
 import { getModelForTier, getModelContextWindow } from '../models/index.js';
 import { generateCustomAgentSystemPrompt, getCustomAgentToolFilter } from './custom-agents.js';
-import { getToolsForProfile, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+import { getToolsForProfile, PROFILE_INFO, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
 /**
  * Estimate token count from text (approximate: ~4 chars per token)
  */
@@ -18,34 +18,64 @@ function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
 /**
- * Did the tool profile get strictly smaller?
+ * Did the agent's reach 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.
+ * ⚠️ TWO TESTS, NOT ONE, and the first version had only half of the first.
+ *
+ * Losing the ability to WRITE is the narrowing that matters most, so a move into a read-only
+ * profile counts however the tool counts land. But it is not the only one: `full` → `custom`
+ * with no groups is total tool removal — the largest narrowing there is — and neither profile
+ * is read-only, so a read-only test alone called it no change at all.
+ *
+ * ⚠️ `undefined` IS NOT "UNKNOWN". `initialize` passes `toolFilter` straight to the factory,
+ * and an absent filter means NO filter — every tool. So `undefined` → `read-only` is the
+ * maximal narrowing, and the original returned false for it. My own test asserted exactly
+ * that under the name "says nothing when either side is unknown", which is how it survived:
+ * the suite encoded the defect as intended behaviour.
  */
 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);
+    const couldWrite = before === undefined || !isReadOnlyProfile(before);
+    const canWrite = after === undefined || !isReadOnlyProfile(after);
+    if (couldWrite && !canWrite)
+        return true;
+    // Otherwise compare what it may actually reach — `undefined` is every tool.
+    return toolReach(after) < toolReach(before);
 }
 /**
- * The profiles that cannot change files.
+ * Did the agent specifically lose the ability to change files?
  *
- * ⚠️ Kept in step with `PROFILE_INFO.isReadOnly` by a test, not by discipline — this module
- * cannot import tool-config without a cycle.
+ * ⚠️ A NARROWER QUESTION THAN `isNarrowing`, and the host needs both. "Fewer tools" and
+ * "cannot write any more" are different facts, and a notice that says "it can no longer
+ * change files" when the agent merely dropped six tools is a false statement in the
+ * transcript — exactly the class of error this whole review found.
  */
-const READ_ONLY_PROFILES = new Set([
-    'read-only',
-    'security',
-    'qa',
-    'architect',
-    'planner',
-    'analyst',
-    'designer',
-]);
+export function lostWriteAccess(before, after) {
+    if (before === after)
+        return false;
+    const couldWrite = before === undefined || !isReadOnlyProfile(before);
+    const canWrite = after === undefined || !isReadOnlyProfile(after);
+    return couldWrite && !canWrite;
+}
+/*
+  ⚠️ NO DEFENSIVE LOOKUP HERE — the profile is validated at the boundary instead.
+  `PROFILE_INFO` is a total Record over `ToolProfile`, so a guard here is dead code by the
+  type system's reckoning and ESLint says so. The real risk is a bogus string arriving over
+  IPC, and the honest place to refuse that is once, on the way in, rather than to absorb it
+  silently at every reader. See `isKnownProfile` and its use in `updateAgent`.
+*/
+const isReadOnlyProfile = (p) => PROFILE_INFO[p].isReadOnly;
+/** Is this a profile the registry actually knows? Used to refuse bad IPC data. */
+export function isKnownProfile(p) {
+    return typeof p === 'string' && Object.prototype.hasOwnProperty.call(PROFILE_INFO, p);
+}
+/** How many tools a profile grants. `undefined` means no filter, i.e. all of them. */
+function toolReach(p) {
+    if (p === undefined)
+        return Number.POSITIVE_INFINITY;
+    return getToolsForProfile(p).length;
+}
 /** Order-insensitive comparison — a reordered skill list is not a change. */
 function sameStrings(a, b) {
     if (a === undefined || b === undefined)
@@ -269,8 +299,26 @@ export class TeamAgent {
             this.description = patch.description;
         if (patch.systemPromptAddition !== undefined)
             this.systemPromptAddition = patch.systemPromptAddition;
-        if (patch.toolProfile !== undefined)
+        /*
+          ⚠️ THE PROFILE IS A LABEL; `toolFilter` IS THE ENFORCEMENT. `initialize()` passes
+          `toolFilter` to the factory and never looks at `toolProfile`, so setting the profile
+          alone changed the word on screen and nothing else: an agent switched to `read-only`
+          kept `write_file` and 168 other tools, while `toolsNarrowed` truthfully reported that
+          its reach had shrunk. A security control that confirms and does not engage.
+    
+          All four CONSTRUCTION sites already derive it — `fromSerialized`, `fromRole`,
+          `fromSpecialist`, `fromCustomDefinition` — which is why a restart applied the
+          restriction the running session had ignored, and why creating a read-only agent was
+          correct all along. Update was the only path that did not.
+    
+          An explicit `toolFilter` still wins: `custom` profiles carry their own list.
+        */
+        if (patch.toolProfile !== undefined) {
             this.toolProfile = patch.toolProfile;
+            if (patch.toolFilter === undefined) {
+                this.toolFilter = getToolsForProfile(patch.toolProfile);
+            }
+        }
         if (patch.toolFilter !== undefined)
             this.toolFilter = patch.toolFilter;
         if (patch.enabledSkills !== undefined)

package/dist/team/team.js

@@ -11,7 +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 { isNarrowing, isKnownProfile, lostWriteAccess } from './team-agent.js';
 import { resolveAgentIdCollision } from './collision-utils.js';
 /**
  * AgentTeam orchestrates multiple persistent agents
@@ -339,6 +339,14 @@ export class AgentTeam {
             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.');
         }
+        /*
+          ⚠️ An unknown profile would otherwise be absorbed silently: `getToolsForProfile` returns
+          nothing for it, so the agent would end up with an empty filter — every tool removed —
+          while the UI showed whatever string was sent. Refuse it here, once.
+        */
+        if (patch.toolProfile !== undefined && !isKnownProfile(patch.toolProfile)) {
+            throw new Error(`Unknown tool profile '${String(patch.toolProfile)}'`);
+        }
         const previousProfile = agent.toolProfile;
         const { rebuilt } = agent.applyUpdate(patch);
         if (rebuilt) {
@@ -352,6 +360,8 @@ export class AgentTeam {
         return {
             rebuilt,
             toolsNarrowed: isNarrowing(previousProfile, agent.toolProfile),
+            /* ⚠️ The narrower fact, so the host can word the notice truthfully. */
+            lostWriteAccess: lostWriteAccess(previousProfile, agent.toolProfile),
             previousProfile,
             newProfile: agent.toolProfile,
         };

package/package.json

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