@compilr-dev/sdk 0.10.17 → 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, } 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, 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, } 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/handoff-orchestration.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Handoff orchestration helpers.
+ *
+ * The `createHandoffTool` factory (delegation-tools.ts) covers the
+ * tool-side of handoffs: validation, one-hop enforcement, `team.recordHandoff`.
+ * What it does NOT cover is the post-turn orchestration pattern shared by
+ * all hosts that surface this tool — stashing the dispatched intent during
+ * the source agent's turn, picking it back up once the turn ends, and
+ * dispatching the task to the target agent.
+ *
+ * Hosts (CLI, Desktop) used to implement that pattern independently,
+ * which is exactly the kind of drift that produced the desktop's
+ * silent-stub bug. This module centralises:
+ *
+ *  - **HandoffIntent** — the shape both hosts pass between "tool fired"
+ *    and "source turn ended."
+ *  - **buildHandoffTaskMessage** — canonical `[Handoff from $arch]\n\nTask:`
+ *    format so the synthesised message the target receives is identical
+ *    across hosts.
+ *  - **validateHandoffIntent** — re-checks team state at dispatch time
+ *    (target could have been removed between stash and pickup).
+ *  - **HandoffStash** — optional convenience for hosts that have multiple
+ *    independent conversations (Desktop). CLI's single-REPL pattern is
+ *    simpler than this class warrants; it can use the type + helpers
+ *    directly without the stash.
+ *
+ * Storage location is intentionally platform-shaped (CLI: one global,
+ * Desktop: per-conversation map) — only the *what* gets standardised,
+ * not the *where*.
+ */
+import type { AgentTeam } from './team.js';
+/**
+ * The intent recorded when a specialist agent calls `handoff(...)`.
+ * Stashed during the source agent's turn, consumed when the turn ends so
+ * the target agent can be invoked with the task.
+ *
+ * `conversationId` is opaque to the SDK — hosts use it to scope stashed
+ * intents (Desktop's per-conversation map; CLI can use a constant like
+ * `'default'` because there's only one REPL session).
+ */
+export interface HandoffIntent {
+    /** Host-defined conversation key. Opaque to the SDK. */
+    conversationId: string;
+    /** Agent that called `handoff`. */
+    sourceAgentId: string;
+    /** Agent receiving the handoff. */
+    targetAgentId: string;
+    /** Task description passed verbatim to the target. */
+    task: string;
+    /** Optional reason text the source provided. */
+    reason?: string;
+}
+/**
+ * Build the synthesised user-style message handed to the target agent
+ * after a successful handoff. Wrapping the body with a `[Handoff from $X]`
+ * marker keeps the target oriented and gives future tooling a way to
+ * distinguish handoff-injected messages from direct user input.
+ *
+ * Format:
+ *
+ *     [Handoff from $arch]
+ *
+ *     Task: <verbatim task>
+ *
+ *     Reason: <verbatim reason — omitted when absent>
+ */
+export declare function buildHandoffTaskMessage(intent: HandoffIntent): string;
+/**
+ * Result of `validateHandoffIntent`. A discriminated union so call sites
+ * can `if (!result.valid) ... result.reason`.
+ */
+export type HandoffValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Re-validate a stashed `HandoffIntent` against the current team state.
+ *
+ * The intent was validated by `createHandoffTool` at the moment the tool
+ * fired, but team state can change between stash and dispatch — an agent
+ * may have been removed, the team may have been swapped out, etc. Hosts
+ * should call this before invoking the target agent.
+ *
+ * Returns `{ valid: false, reason }` with a user-readable message when
+ * the intent is no longer dispatchable.
+ */
+export declare function validateHandoffIntent(team: AgentTeam, intent: HandoffIntent): HandoffValidationResult;
+/**
+ * Per-conversation stash for `HandoffIntent`s. Hosts that manage multiple
+ * independent conversations (the Desktop app) can use this directly; the
+ * CLI's single-REPL pattern is simpler than this class warrants and can
+ * use plain fields on its shared-state object.
+ *
+ * Usage:
+ *
+ *     // Inside the handoff tool's `onHandoff` adapter callback:
+ *     stash.set({ conversationId, sourceAgentId, targetAgentId, task, reason });
+ *
+ *     // After the source agent's turn ends:
+ *     const intent = stash.consume(conversationId);
+ *     if (intent) {
+ *       const check = validateHandoffIntent(team, intent);
+ *       if (check.valid) {
+ *         await runTargetAgent(intent.targetAgentId, buildHandoffTaskMessage(intent));
+ *       }
+ *     }
+ */
+export declare class HandoffStash {
+    private readonly intents;
+    /** Stash an intent. Replaces any prior intent for the same conversation
+     *  — only one handoff can be in flight per conversation at a time. */
+    set(intent: HandoffIntent): void;
+    /** Read without removing. Useful for "is there a handoff pending?" UI checks. */
+    peek(conversationId: string): HandoffIntent | undefined;
+    /** Read and remove. The normal post-turn pickup pattern. */
+    consume(conversationId: string): HandoffIntent | undefined;
+    /** Explicitly clear without consuming — used by error paths so a failed
+     *  source turn doesn't leave a phantom intent for the next turn. */
+    clear(conversationId: string): void;
+    /** Whether a stashed intent exists for this conversation. */
+    has(conversationId: string): boolean;
+}

package/dist/team/handoff-orchestration.js

@@ -0,0 +1,128 @@
+/**
+ * Handoff orchestration helpers.
+ *
+ * The `createHandoffTool` factory (delegation-tools.ts) covers the
+ * tool-side of handoffs: validation, one-hop enforcement, `team.recordHandoff`.
+ * What it does NOT cover is the post-turn orchestration pattern shared by
+ * all hosts that surface this tool — stashing the dispatched intent during
+ * the source agent's turn, picking it back up once the turn ends, and
+ * dispatching the task to the target agent.
+ *
+ * Hosts (CLI, Desktop) used to implement that pattern independently,
+ * which is exactly the kind of drift that produced the desktop's
+ * silent-stub bug. This module centralises:
+ *
+ *  - **HandoffIntent** — the shape both hosts pass between "tool fired"
+ *    and "source turn ended."
+ *  - **buildHandoffTaskMessage** — canonical `[Handoff from $arch]\n\nTask:`
+ *    format so the synthesised message the target receives is identical
+ *    across hosts.
+ *  - **validateHandoffIntent** — re-checks team state at dispatch time
+ *    (target could have been removed between stash and pickup).
+ *  - **HandoffStash** — optional convenience for hosts that have multiple
+ *    independent conversations (Desktop). CLI's single-REPL pattern is
+ *    simpler than this class warrants; it can use the type + helpers
+ *    directly without the stash.
+ *
+ * Storage location is intentionally platform-shaped (CLI: one global,
+ * Desktop: per-conversation map) — only the *what* gets standardised,
+ * not the *where*.
+ */
+// =============================================================================
+// Canonical task-message format
+// =============================================================================
+/**
+ * Build the synthesised user-style message handed to the target agent
+ * after a successful handoff. Wrapping the body with a `[Handoff from $X]`
+ * marker keeps the target oriented and gives future tooling a way to
+ * distinguish handoff-injected messages from direct user input.
+ *
+ * Format:
+ *
+ *     [Handoff from $arch]
+ *
+ *     Task: <verbatim task>
+ *
+ *     Reason: <verbatim reason — omitted when absent>
+ */
+export function buildHandoffTaskMessage(intent) {
+    return intent.reason
+        ? `[Handoff from $${intent.sourceAgentId}]\n\nTask: ${intent.task}\n\nReason: ${intent.reason}`
+        : `[Handoff from $${intent.sourceAgentId}]\n\nTask: ${intent.task}`;
+}
+/**
+ * Re-validate a stashed `HandoffIntent` against the current team state.
+ *
+ * The intent was validated by `createHandoffTool` at the moment the tool
+ * fired, but team state can change between stash and dispatch — an agent
+ * may have been removed, the team may have been swapped out, etc. Hosts
+ * should call this before invoking the target agent.
+ *
+ * Returns `{ valid: false, reason }` with a user-readable message when
+ * the intent is no longer dispatchable.
+ */
+export function validateHandoffIntent(team, intent) {
+    if (!team.has(intent.targetAgentId)) {
+        return {
+            valid: false,
+            reason: `Agent '${intent.targetAgentId}' no longer exists in team.`,
+        };
+    }
+    if (!team.has(intent.sourceAgentId)) {
+        return {
+            valid: false,
+            reason: `Source agent '${intent.sourceAgentId}' no longer exists in team.`,
+        };
+    }
+    return { valid: true };
+}
+// =============================================================================
+// Optional stash for multi-conversation hosts (Desktop)
+// =============================================================================
+/**
+ * Per-conversation stash for `HandoffIntent`s. Hosts that manage multiple
+ * independent conversations (the Desktop app) can use this directly; the
+ * CLI's single-REPL pattern is simpler than this class warrants and can
+ * use plain fields on its shared-state object.
+ *
+ * Usage:
+ *
+ *     // Inside the handoff tool's `onHandoff` adapter callback:
+ *     stash.set({ conversationId, sourceAgentId, targetAgentId, task, reason });
+ *
+ *     // After the source agent's turn ends:
+ *     const intent = stash.consume(conversationId);
+ *     if (intent) {
+ *       const check = validateHandoffIntent(team, intent);
+ *       if (check.valid) {
+ *         await runTargetAgent(intent.targetAgentId, buildHandoffTaskMessage(intent));
+ *       }
+ *     }
+ */
+export class HandoffStash {
+    intents = new Map();
+    /** Stash an intent. Replaces any prior intent for the same conversation
+     *  — only one handoff can be in flight per conversation at a time. */
+    set(intent) {
+        this.intents.set(intent.conversationId, intent);
+    }
+    /** Read without removing. Useful for "is there a handoff pending?" UI checks. */
+    peek(conversationId) {
+        return this.intents.get(conversationId);
+    }
+    /** Read and remove. The normal post-turn pickup pattern. */
+    consume(conversationId) {
+        const intent = this.intents.get(conversationId);
+        this.intents.delete(conversationId);
+        return intent;
+    }
+    /** Explicitly clear without consuming — used by error paths so a failed
+     *  source turn doesn't leave a phantom intent for the next turn. */
+    clear(conversationId) {
+        this.intents.delete(conversationId);
+    }
+    /** Whether a stashed intent exists for this conversation. */
+    has(conversationId) {
+        return this.intents.has(conversationId);
+    }
+}

package/dist/team/index.d.ts

@@ -40,3 +40,7 @@ export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSk
 export { resolveAgentIdCollision } from './collision-utils.js';
 export { createDelegationStatusTool, createHandoffTool } from './delegation-tools.js';
 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

@@ -33,3 +33,10 @@ export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSk
 export { resolveAgentIdCollision } from './collision-utils.js';
 // Delegation & Handoff tools (factory functions)
 export { createDelegationStatusTool, createHandoffTool } from './delegation-tools.js';
+// 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.17",
+  "version": "0.10.19",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",