@compilr-dev/sdk 0.10.7 → 0.10.8

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, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, } 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, 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, 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, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, } 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/delegation-tools.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Delegation & Handoff Tools — SDK Factories
+ *
+ * Factory functions for creating delegation_status and handoff tools.
+ * Both CLI and Desktop call these with platform-specific dependencies.
+ */
+import { type Tool } from '@compilr-dev/agents';
+import type { DelegationTracker } from './delegation-tracker.js';
+import type { AgentTeam } from './team.js';
+interface DelegationStatusInput {
+    delegation_id?: string;
+    agent_id?: string;
+    status?: 'active' | 'completed' | 'failed' | 'all';
+}
+/**
+ * Create a delegation_status tool that queries the given tracker.
+ * Read-only — safe for parallel execution.
+ */
+export declare function createDelegationStatusTool(tracker: DelegationTracker): Tool<DelegationStatusInput>;
+interface HandoffInput {
+    agentId: string;
+    task: string;
+    reason?: string;
+}
+/**
+ * Result from the platform's handoff handler.
+ */
+export interface HandoffResult {
+    /** Whether the handoff was executed */
+    success: boolean;
+    /** Whether the user declined the handoff */
+    declined?: boolean;
+    /** Error message (if any) */
+    error?: string;
+}
+/**
+ * Configuration for creating a handoff tool.
+ */
+export interface HandoffToolConfig {
+    /** The team instance for roster validation and one-hop tracking */
+    team: AgentTeam;
+    /** The current agent's ID (for one-hop rule enforcement) */
+    currentAgentId: string;
+    /**
+     * Platform-specific handoff handler. Called after validation.
+     * Should show approval UI if needed and execute the switch.
+     */
+    onHandoff: (targetAgentId: string, task: string, reason?: string) => Promise<HandoffResult>;
+}
+/**
+ * Create a handoff tool for a specific agent.
+ *
+ * The tool enforces the one-hop rule: if this agent was itself handed a task,
+ * it can only hand back to the coordinator (default agent), not to another specialist.
+ */
+export declare function createHandoffTool(config: HandoffToolConfig): Tool<HandoffInput>;
+export {};

package/dist/team/delegation-tools.js

@@ -0,0 +1,224 @@
+/**
+ * Delegation & Handoff Tools — SDK Factories
+ *
+ * Factory functions for creating delegation_status and handoff tools.
+ * Both CLI and Desktop call these with platform-specific dependencies.
+ */
+import { defineTool } from '@compilr-dev/agents';
+function formatDuration(from, to) {
+    const endTime = to ?? new Date();
+    const ms = endTime.getTime() - from.getTime();
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        return `${String(hours)}h ${String(minutes % 60)}m`;
+    }
+    else if (minutes > 0) {
+        return `${String(minutes)}m ${String(seconds % 60)}s`;
+    }
+    else {
+        return `${String(seconds)}s`;
+    }
+}
+function formatDelegation(d) {
+    const entry = {
+        id: d.id,
+        targetAgent: d.targetAgentId,
+        task: d.task.length > 100 ? d.task.slice(0, 100) + '...' : d.task,
+        status: d.status,
+        duration: formatDuration(d.createdAt, d.completedAt),
+    };
+    if (d.todoIndex !== undefined) {
+        entry.todoIndex = d.todoIndex;
+    }
+    if (d.result) {
+        entry.result = {
+            success: d.result.success,
+            summary: d.result.summary,
+            artifactIds: d.result.artifactIds,
+            ...(d.result.error ? { error: d.result.error } : {}),
+        };
+    }
+    return entry;
+}
+/**
+ * Create a delegation_status tool that queries the given tracker.
+ * Read-only — safe for parallel execution.
+ */
+export function createDelegationStatusTool(tracker) {
+    return defineTool({
+        name: 'delegation_status',
+        description: 'Query the status of tasks delegated via delegate_background. ' +
+            'Returns active delegations by default (pending and running). ' +
+            'Use delegation_id for a specific delegation, agent_id to filter by agent, ' +
+            'or status to see completed/failed/all delegations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                delegation_id: {
+                    type: 'string',
+                    description: 'Specific delegation ID (e.g., "del_abc12345")',
+                },
+                agent_id: {
+                    type: 'string',
+                    description: 'Filter by target agent (e.g., "dev", "arch")',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'completed', 'failed', 'all'],
+                    description: 'Filter by status. Default: "active" (pending + running)',
+                },
+            },
+        },
+        execute: (input) => {
+            return Promise.resolve(executeDelegationStatus(tracker, input));
+        },
+    });
+}
+function executeDelegationStatus(tracker, input) {
+    // Single delegation lookup
+    if (input.delegation_id) {
+        const delegation = tracker.getDelegation(input.delegation_id);
+        if (!delegation) {
+            return {
+                success: false,
+                error: `Delegation ${input.delegation_id} not found`,
+            };
+        }
+        return {
+            success: true,
+            result: {
+                delegations: [formatDelegation(delegation)],
+                stats: tracker.getStats(),
+            },
+        };
+    }
+    // Get all delegations then filter
+    let delegations;
+    if (input.agent_id) {
+        delegations = tracker.getByAgent(input.agent_id);
+    }
+    else {
+        delegations = tracker.getAll();
+    }
+    // Apply status filter
+    const filter = input.status ?? 'active';
+    if (filter !== 'all') {
+        delegations = delegations.filter((d) => {
+            switch (filter) {
+                case 'active':
+                    return d.status === 'pending' || d.status === 'running';
+                case 'completed':
+                    return d.status === 'completed';
+                case 'failed':
+                    return d.status === 'failed';
+                default:
+                    return true;
+            }
+        });
+    }
+    return {
+        success: true,
+        result: {
+            delegations: delegations.map(formatDelegation),
+            stats: tracker.getStats(),
+        },
+    };
+}
+/**
+ * Create a handoff tool for a specific agent.
+ *
+ * The tool enforces the one-hop rule: if this agent was itself handed a task,
+ * it can only hand back to the coordinator (default agent), not to another specialist.
+ */
+export function createHandoffTool(config) {
+    const { team, currentAgentId, onHandoff } = config;
+    return defineTool({
+        name: 'handoff',
+        description: 'Hand off the current task to another team agent. ' +
+            'Use this when a task is outside your expertise or would benefit from another specialist. ' +
+            'The user will be asked to approve the handoff before switching. ' +
+            'Example: hand off architecture questions to $arch, implementation to $dev, testing to $qa.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: {
+                    type: 'string',
+                    description: 'Target agent ID (e.g., "arch", "dev", "qa", "default")',
+                },
+                task: {
+                    type: 'string',
+                    description: 'Task description for the target agent - be specific and clear',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Why this agent is better suited for the task (shown to user)',
+                },
+            },
+            required: ['agentId', 'task'],
+        },
+        execute: async (input) => {
+            // Validate input
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return { success: false, error: 'Agent ID is required' };
+            }
+            if (!input.task || input.task.trim().length === 0) {
+                return { success: false, error: 'Task description is required' };
+            }
+            const targetId = input.agentId.trim();
+            // Validate target agent exists in team
+            const allAgents = team.getAll();
+            const targetExists = allAgents.some((a) => a.id === targetId);
+            if (!targetExists) {
+                const available = allAgents.map((a) => a.id).join(', ');
+                return {
+                    success: false,
+                    error: `Agent "${targetId}" not found in team. Available: ${available}`,
+                };
+            }
+            // Enforce one-hop rule
+            if (team.wasHandedTo(currentAgentId) && targetId !== 'default') {
+                const source = team.getHandoffSource(currentAgentId);
+                return {
+                    success: false,
+                    error: `One-hop rule: you were handed this task by $${source ?? 'unknown'} ` +
+                        `and cannot re-hand it to another specialist. ` +
+                        `You can only hand back to $default (coordinator). ` +
+                        `Either complete the task yourself or hand back to the coordinator.`,
+                };
+            }
+            // Execute handoff via platform callback
+            try {
+                const result = await onHandoff(targetId, input.task.trim(), input.reason?.trim());
+                if (result.error) {
+                    return { success: false, error: result.error };
+                }
+                if (result.declined) {
+                    return {
+                        success: true,
+                        result: {
+                            handedOff: false,
+                            message: 'User declined the handoff. Continue handling the task yourself.',
+                        },
+                    };
+                }
+                // Record the handoff for one-hop tracking
+                team.recordHandoff(targetId, currentAgentId);
+                return {
+                    success: true,
+                    result: {
+                        handedOff: true,
+                        message: `Task handed off to $${targetId}. They will handle it from here.`,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Handoff failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+}

package/dist/team/index.d.ts

@@ -38,3 +38,5 @@ export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } fr
 export type { SkillToolRequirement } from './skill-requirements.js';
 export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
 export { resolveAgentIdCollision } from './collision-utils.js';
+export { createDelegationStatusTool, createHandoffTool } from './delegation-tools.js';
+export type { HandoffResult, HandoffToolConfig } from './delegation-tools.js';

package/dist/team/index.js

@@ -31,3 +31,5 @@ export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } fr
 export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
 // Collision utils
 export { resolveAgentIdCollision } from './collision-utils.js';
+// Delegation & Handoff tools (factory functions)
+export { createDelegationStatusTool, createHandoffTool } from './delegation-tools.js';

package/package.json

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