@compilr-dev/sdk 0.10.18 → 0.10.19

package/dist/index.d.ts

@@ -35,9 +35,9 @@
  */
 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, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, ROLE_NAME_ALIASES, normalizeRoleName, } from './team/index.js';
 export type { AgentTeamConfig, TeamAgentConfig, 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, SkillToolRequirement, } 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, 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, 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 { codingPreset, readOnlyPreset, resolvePreset } from './presets/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, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, ROLE_NAME_ALIASES, normalizeRoleName, } 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

@@ -42,3 +42,5 @@ export { createDelegationStatusTool, createHandoffTool } from './delegation-tool
 export type { HandoffResult, HandoffToolConfig } from './delegation-tools.js';
 export { buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, } from './handoff-orchestration.js';
 export type { HandoffIntent, HandoffValidationResult } from './handoff-orchestration.js';
+export { ROLE_NAME_ALIASES, normalizeRoleName } from './role-aliases.js';
+export type { NormalizedRole } from './role-aliases.js';

package/dist/team/index.js

@@ -36,3 +36,7 @@ export { createDelegationStatusTool, createHandoffTool } from './delegation-tool
 // Handoff orchestration helpers — shared between CLI and Desktop for the
 // post-turn stash/dispatch pattern. See handoff-orchestration.ts header.
 export { buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, } from './handoff-orchestration.js';
+// Role-name aliases — longform → canonical AgentRole short key. Shared
+// between CLI and Desktop for `suggestedAgents` translation when batch-
+// adding a project type's default team. See role-aliases.ts header.
+export { ROLE_NAME_ALIASES, normalizeRoleName } from './role-aliases.js';

package/dist/team/role-aliases.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Role-name aliases — longform → canonical AgentRole short key.
+ *
+ * The project-type configs (`src/project-types/configs.ts`) use a mix of
+ * longform role names (`developer`, `architect`, `technical-writer`) and
+ * canonical short keys (`qa`, `pm`, `writer`, `researcher`) in their
+ * `suggestedAgents` lists. `TeamAgent.addAgentFromRole` only accepts the
+ * canonical short keys (`AgentRole`).
+ *
+ * Hosts (CLI, Desktop) that auto-add `suggestedAgents` into a team need
+ * to translate the mixed input to the canonical form before calling
+ * `addAgentFromRole`. This module is the single source of truth for that
+ * mapping — previously duplicated between the desktop's
+ * `lib/role-mascots.ts:toSdkRole` and the CLI's inline `LONG_TO_SHORT`
+ * map in `commands-v2/handlers/project.ts`.
+ *
+ * The alias targets are best-fit mappings, not exact equivalents:
+ *   security → reviewer  (security review work, no dedicated agent yet)
+ *   designer → default   (no design agent yet)
+ *   plotter / scene-writer / character-dev / content-designer → writer
+ *     (writing-adjacent roles that share the writer agent)
+ *
+ * When a new TeamAgent role is added to `AgentRole`, prefer that role
+ * over the alias here. E.g., when a real `security` TeamAgent ships,
+ * update the alias to `security → security` (or remove the alias and
+ * add `security` to `AgentRole` so it's pass-through).
+ */
+import type { AgentRole } from './types.js';
+/** Longform role names mapped to canonical AgentRole short keys. */
+export declare const ROLE_NAME_ALIASES: Record<string, AgentRole>;
+/** Result of `normalizeRoleName`. Three states: pass-through (the input was
+ *  already canonical), mapped (an alias was applied), or unknown (input is
+ *  neither and we fell back to `'default'`). */
+export interface NormalizedRole {
+    /** The canonical short AgentRole. */
+    role: AgentRole;
+    /** True if `ROLE_NAME_ALIASES` rewrote the input. */
+    mapped: boolean;
+    /** True if the input was neither a canonical role nor a known alias.
+     *  Callers can either treat this as an error or accept the `'default'`
+     *  fallback that's been set on `role`. */
+    unknown: boolean;
+}
+/**
+ * Normalise a role name to the canonical `AgentRole`.
+ *
+ * Behaviour:
+ *  - Input is already a canonical short key → pass through, `mapped: false`,
+ *    `unknown: false`.
+ *  - Input matches a known longform alias → mapped to the canonical key,
+ *    `mapped: true`, `unknown: false`.
+ *  - Input is neither → returns `'default'`, `mapped: false`, `unknown: true`.
+ *    Callers typically log/warn and skip rather than silently add the
+ *    default agent.
+ *
+ * @example
+ *   normalizeRoleName('developer')  // { role: 'dev', mapped: true, unknown: false }
+ *   normalizeRoleName('qa')         // { role: 'qa', mapped: false, unknown: false }
+ *   normalizeRoleName('astronaut')  // { role: 'default', mapped: false, unknown: true }
+ */
+export declare function normalizeRoleName(role: string): NormalizedRole;

package/dist/team/role-aliases.js

@@ -0,0 +1,69 @@
+/**
+ * Role-name aliases — longform → canonical AgentRole short key.
+ *
+ * The project-type configs (`src/project-types/configs.ts`) use a mix of
+ * longform role names (`developer`, `architect`, `technical-writer`) and
+ * canonical short keys (`qa`, `pm`, `writer`, `researcher`) in their
+ * `suggestedAgents` lists. `TeamAgent.addAgentFromRole` only accepts the
+ * canonical short keys (`AgentRole`).
+ *
+ * Hosts (CLI, Desktop) that auto-add `suggestedAgents` into a team need
+ * to translate the mixed input to the canonical form before calling
+ * `addAgentFromRole`. This module is the single source of truth for that
+ * mapping — previously duplicated between the desktop's
+ * `lib/role-mascots.ts:toSdkRole` and the CLI's inline `LONG_TO_SHORT`
+ * map in `commands-v2/handlers/project.ts`.
+ *
+ * The alias targets are best-fit mappings, not exact equivalents:
+ *   security → reviewer  (security review work, no dedicated agent yet)
+ *   designer → default   (no design agent yet)
+ *   plotter / scene-writer / character-dev / content-designer → writer
+ *     (writing-adjacent roles that share the writer agent)
+ *
+ * When a new TeamAgent role is added to `AgentRole`, prefer that role
+ * over the alias here. E.g., when a real `security` TeamAgent ships,
+ * update the alias to `security → security` (or remove the alias and
+ * add `security` to `AgentRole` so it's pass-through).
+ */
+import { PREDEFINED_ROLE_IDS } from './types.js';
+/** Longform role names mapped to canonical AgentRole short keys. */
+export const ROLE_NAME_ALIASES = {
+    developer: 'dev',
+    architect: 'arch',
+    'technical-writer': 'docs',
+    security: 'reviewer',
+    designer: 'default',
+    'character-dev': 'writer',
+    'content-designer': 'writer',
+    plotter: 'writer',
+    'scene-writer': 'writer',
+};
+const SDK_ROLE_PASSTHROUGH = new Set(PREDEFINED_ROLE_IDS);
+/**
+ * Normalise a role name to the canonical `AgentRole`.
+ *
+ * Behaviour:
+ *  - Input is already a canonical short key → pass through, `mapped: false`,
+ *    `unknown: false`.
+ *  - Input matches a known longform alias → mapped to the canonical key,
+ *    `mapped: true`, `unknown: false`.
+ *  - Input is neither → returns `'default'`, `mapped: false`, `unknown: true`.
+ *    Callers typically log/warn and skip rather than silently add the
+ *    default agent.
+ *
+ * @example
+ *   normalizeRoleName('developer')  // { role: 'dev', mapped: true, unknown: false }
+ *   normalizeRoleName('qa')         // { role: 'qa', mapped: false, unknown: false }
+ *   normalizeRoleName('astronaut')  // { role: 'default', mapped: false, unknown: true }
+ */
+export function normalizeRoleName(role) {
+    if (SDK_ROLE_PASSTHROUGH.has(role)) {
+        return { role: role, mapped: false, unknown: false };
+    }
+    // hasOwn is needed because Record<string, T> reports every string key as
+    // present at the type level even when it isn't — we need the runtime check.
+    if (Object.prototype.hasOwnProperty.call(ROLE_NAME_ALIASES, role)) {
+        return { role: ROLE_NAME_ALIASES[role], mapped: true, unknown: false };
+    }
+    return { role: 'default', mapped: false, unknown: true };
+}

package/package.json

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