@compilr-dev/sdk 0.10.35 → 0.10.37

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, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, 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, ConsultInput, ConsultResult, ConsultToolConfig, NormalizedRole, 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, 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, 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, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, } from './team/index.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, 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/delegation-tools.d.ts

@@ -1,8 +1,12 @@
 /**
  * Delegation & Handoff Tools — SDK Factories
  *
- * Factory functions for creating delegation_status and handoff tools.
- * Both CLI and Desktop call these with platform-specific dependencies.
+ * Factory functions for creating delegation_status, handoff, delegate, and
+ * delegate_background tools. Both CLI and Desktop call these with
+ * platform-specific dependencies.
+ *
+ * Canonical semantics: see
+ * project-docs/00-requirements/compilr-dev-sdk/multi-agent-tools-taxonomy-spec.md
  */
 import { type Tool } from '@compilr-dev/agents';
 import type { DelegationTracker } from './delegation-tracker.js';
@@ -54,4 +58,127 @@ export interface HandoffToolConfig {
  * it can only hand back to the coordinator (default agent), not to another specialist.
  */
 export declare function createHandoffTool(config: HandoffToolConfig): Tool<HandoffInput>;
+interface DelegateInput {
+    agentId: string;
+    task: string;
+    reason?: string;
+}
+/**
+ * Result from the platform's delegate handler.
+ *
+ * The factory normalises this into the tool's result body — the agent
+ * sees `response` as the specialist's reply when delegation succeeded.
+ */
+export interface DelegateResult {
+    /** True if delegation completed (approval granted + specialist ran). */
+    success: boolean;
+    /** True if the user declined the delegation via the approval overlay. */
+    declined?: boolean;
+    /** Specialist's final response text (populated when success=true). */
+    response?: string;
+    /** Error description (when success=false). */
+    error?: string;
+}
+/**
+ * Configuration for creating a delegate tool.
+ */
+export interface DelegateToolConfig {
+    /** The team instance for roster validation. */
+    team: AgentTeam;
+    /** The current agent's ID (must be 'default' — coordinator-only tool). */
+    currentAgentId: string;
+    /**
+     * Platform-specific delegate handler. Called after validation.
+     *
+     * The host implementation should:
+     *   1. (Optional) Show approval UI to the user.
+     *   2. Run the specialist's task in their persistent context.
+     *   3. Return the specialist's response. The factory surfaces this
+     *      response in the coordinator's tool result body.
+     *
+     * If the host wants to truncate long responses, do it inside the
+     * callback before returning.
+     *
+     * For per-context behavior (CLI vs Desktop single-agent vs Desktop
+     * group chat) see multi-agent-tools-taxonomy-spec.md §3.
+     */
+    onDelegate: (targetAgentId: string, task: string, reason?: string) => Promise<DelegateResult>;
+}
+/**
+ * Create a delegate tool for the coordinator agent.
+ *
+ * Semantics (per taxonomy spec §2):
+ *   - Foreground + sync — caller waits for response
+ *   - Caller continues working after the response returns
+ *   - Target remembers the work (persistent context)
+ *   - Direction: coordinator → specialist (enforced — `currentAgentId`
+ *     must be 'default'; the factory rejects with an error otherwise)
+ *
+ * Differentiation:
+ *   - vs `consult` — consult is transient (target doesn't remember).
+ *   - vs `delegate_background` — that's async; delegate blocks for the
+ *     response.
+ *   - vs `handoff` — handoff means the caller is done; delegate gets a
+ *     response and the caller continues.
+ */
+export declare function createDelegateTool(config: DelegateToolConfig): Tool<DelegateInput>;
+interface DelegateBackgroundInput {
+    agentId: string;
+    task: string;
+    todoIndex?: number;
+    expectedOutput?: string;
+}
+/**
+ * Result from the platform's delegate_background handler.
+ */
+export interface DelegateBackgroundResult {
+    /** Unique delegation ID for tracking via delegation_status. */
+    delegationId: string;
+    /** Current status — running (started) or queued (target busy). */
+    status: 'running' | 'queued';
+    /** Error description (when failed). */
+    error?: string;
+}
+/**
+ * Configuration for creating a delegate_background tool.
+ */
+export interface DelegateBackgroundToolConfig {
+    /** The team instance for roster validation. */
+    team: AgentTeam;
+    /** The current agent's ID (must be 'default' — coordinator-only tool). */
+    currentAgentId: string;
+    /**
+     * Platform-specific background delegation handler. Called after validation.
+     *
+     * The host implementation should:
+     *   1. Create a delegation record (in tracker / IPC / wherever the host
+     *      surfaces async status to the user).
+     *   2. Start the specialist running in background (or queue if busy).
+     *   3. Return the delegation ID + initial status so the coordinator can
+     *      poll via delegation_status.
+     *
+     * For per-context behavior (CLI vs Desktop single-agent vs Desktop
+     * group chat) see multi-agent-tools-taxonomy-spec.md §3.
+     */
+    onDelegateBackground: (args: {
+        targetAgentId: string;
+        task: string;
+        todoIndex?: number;
+        expectedOutput?: string;
+    }) => Promise<DelegateBackgroundResult>;
+}
+/**
+ * Create a delegate_background tool for the coordinator agent.
+ *
+ * Semantics (per taxonomy spec §2):
+ *   - Background + async — caller continues immediately
+ *   - Caller polls completion via `delegation_status`
+ *   - Target remembers the work (persistent context)
+ *   - Direction: coordinator → specialist
+ *
+ * Use this when the coordinator wants to dispatch work in parallel and
+ * keep operating. Use `delegate` if the coordinator needs the response
+ * before continuing.
+ */
+export declare function createDelegateBackgroundTool(config: DelegateBackgroundToolConfig): Tool<DelegateBackgroundInput>;
 export {};

package/dist/team/delegation-tools.js

@@ -1,8 +1,12 @@
 /**
  * Delegation & Handoff Tools — SDK Factories
  *
- * Factory functions for creating delegation_status and handoff tools.
- * Both CLI and Desktop call these with platform-specific dependencies.
+ * Factory functions for creating delegation_status, handoff, delegate, and
+ * delegate_background tools. Both CLI and Desktop call these with
+ * platform-specific dependencies.
+ *
+ * Canonical semantics: see
+ * project-docs/00-requirements/compilr-dev-sdk/multi-agent-tools-taxonomy-spec.md
  */
 import { defineTool } from '@compilr-dev/agents';
 function formatDuration(from, to) {
@@ -222,3 +226,236 @@ export function createHandoffTool(config) {
         },
     });
 }
+/**
+ * Create a delegate tool for the coordinator agent.
+ *
+ * Semantics (per taxonomy spec §2):
+ *   - Foreground + sync — caller waits for response
+ *   - Caller continues working after the response returns
+ *   - Target remembers the work (persistent context)
+ *   - Direction: coordinator → specialist (enforced — `currentAgentId`
+ *     must be 'default'; the factory rejects with an error otherwise)
+ *
+ * Differentiation:
+ *   - vs `consult` — consult is transient (target doesn't remember).
+ *   - vs `delegate_background` — that's async; delegate blocks for the
+ *     response.
+ *   - vs `handoff` — handoff means the caller is done; delegate gets a
+ *     response and the caller continues.
+ */
+export function createDelegateTool(config) {
+    const { team, currentAgentId, onDelegate } = config;
+    return defineTool({
+        name: 'delegate',
+        description: 'Delegate a task to a specialist and get their response back. ' +
+            'The specialist runs the task in their persistent context (they remember the work). ' +
+            "You stay in charge — control returns to you with the specialist's response. " +
+            'Use consult if you just want a quick answer without persistence. ' +
+            'Use delegate_background if you want the specialist to work in parallel while you continue. ' +
+            'Use handoff to permanently pass the baton (you stop working). ' +
+            'Only available to the coordinator.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: {
+                    type: 'string',
+                    description: 'Target specialist agent ID (e.g., "arch", "dev", "qa")',
+                },
+                task: {
+                    type: 'string',
+                    description: 'Task description for the specialist — be specific and clear',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Why this specialist is 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();
+            // Enforce coordinator-only — the factory shouldn't be wired up to
+            // non-coordinator agents in the first place, but defensive check.
+            if (currentAgentId !== 'default') {
+                return {
+                    success: false,
+                    error: 'Only the coordinator can delegate tasks. ' +
+                        'Specialists pass work via handoff (peer-to-peer) or consult (sync question).',
+                };
+            }
+            // Prevent self-delegation
+            if (targetId === 'default') {
+                return {
+                    success: false,
+                    error: 'Cannot delegate to yourself (the coordinator). Delegate to a specialist agent.',
+                };
+            }
+            // Validate target agent exists in team
+            const allAgents = team.getAll();
+            const targetExists = allAgents.some((a) => a.id === targetId);
+            if (!targetExists) {
+                const available = allAgents
+                    .filter((a) => a.id !== 'default')
+                    .map((a) => a.id)
+                    .join(', ');
+                return {
+                    success: false,
+                    error: `Agent "${targetId}" not found in team. Available specialists: ${available || '(none)'}`,
+                };
+            }
+            // Execute delegation via platform callback
+            try {
+                const result = await onDelegate(targetId, input.task.trim(), input.reason?.trim());
+                if (result.error) {
+                    return { success: false, error: result.error };
+                }
+                if (result.declined) {
+                    return {
+                        success: true,
+                        result: {
+                            delegated: false,
+                            agent: targetId,
+                            message: 'User declined the delegation. Continue handling the task yourself.',
+                        },
+                    };
+                }
+                return {
+                    success: true,
+                    result: {
+                        delegated: true,
+                        agent: targetId,
+                        response: result.response,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Delegate failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+}
+/**
+ * Create a delegate_background tool for the coordinator agent.
+ *
+ * Semantics (per taxonomy spec §2):
+ *   - Background + async — caller continues immediately
+ *   - Caller polls completion via `delegation_status`
+ *   - Target remembers the work (persistent context)
+ *   - Direction: coordinator → specialist
+ *
+ * Use this when the coordinator wants to dispatch work in parallel and
+ * keep operating. Use `delegate` if the coordinator needs the response
+ * before continuing.
+ */
+export function createDelegateBackgroundTool(config) {
+    const { team, currentAgentId, onDelegateBackground } = config;
+    return defineTool({
+        name: 'delegate_background',
+        description: 'Delegate a task to a specialist running in background. ' +
+            'The specialist executes independently while you continue working. ' +
+            'You will be notified when the specialist completes. ' +
+            'Use delegation_status to check progress. ' +
+            'Prefer this over delegate when you have parallel work to do — it keeps you in control. ' +
+            'Only available to the coordinator.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: {
+                    type: 'string',
+                    description: 'Target specialist agent ID (e.g., "arch", "dev", "qa")',
+                },
+                task: {
+                    type: 'string',
+                    description: 'Detailed task description for the specialist',
+                },
+                todoIndex: {
+                    type: 'number',
+                    description: 'Optional todo index to associate with this delegation',
+                },
+                expectedOutput: {
+                    type: 'string',
+                    description: 'What the specialist should produce (e.g., "architecture document", "implementation")',
+                },
+            },
+            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();
+            // Enforce coordinator-only
+            if (currentAgentId !== 'default') {
+                return {
+                    success: false,
+                    error: 'Only the coordinator can use delegate_background. ' +
+                        'Specialists pass work via handoff (peer-to-peer) or consult (sync question).',
+                };
+            }
+            // Prevent self-delegation
+            if (targetId === 'default') {
+                return {
+                    success: false,
+                    error: 'Cannot delegate to yourself (the coordinator). Delegate to a specialist agent.',
+                };
+            }
+            // Validate target agent exists in team
+            const allAgents = team.getAll();
+            const targetExists = allAgents.some((a) => a.id === targetId);
+            if (!targetExists) {
+                const available = allAgents
+                    .filter((a) => a.id !== 'default')
+                    .map((a) => a.id)
+                    .join(', ');
+                return {
+                    success: false,
+                    error: `Agent "${targetId}" not found in team. Available specialists: ${available || '(none)'}`,
+                };
+            }
+            // Execute background delegation via platform callback
+            try {
+                const result = await onDelegateBackground({
+                    targetAgentId: targetId,
+                    task: input.task.trim(),
+                    todoIndex: input.todoIndex,
+                    expectedOutput: input.expectedOutput?.trim(),
+                });
+                if (result.error) {
+                    return { success: false, error: result.error };
+                }
+                return {
+                    success: true,
+                    result: {
+                        delegated: true,
+                        agent: targetId,
+                        delegationId: result.delegationId,
+                        status: result.status,
+                        message: result.status === 'queued'
+                            ? `Task queued for $${targetId} (currently busy). It will start when they're free.`
+                            : `Task delegated to $${targetId} running in background. You'll be notified on completion. Use delegation_status to check progress.`,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Background delegation failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+}

package/dist/team/index.d.ts

@@ -38,8 +38,8 @@ 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';
+export { createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, } from './delegation-tools.js';
+export type { HandoffResult, HandoffToolConfig, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, } from './delegation-tools.js';
 export { buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, } from './handoff-orchestration.js';
 export type { HandoffIntent, HandoffValidationResult } from './handoff-orchestration.js';
 export { createConsultTool, buildConsultQuestionMessage } from './consult-tool.js';

package/dist/team/index.js

@@ -32,7 +32,7 @@ export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSk
 // Collision utils
 export { resolveAgentIdCollision } from './collision-utils.js';
 // Delegation & Handoff tools (factory functions)
-export { createDelegationStatusTool, createHandoffTool } from './delegation-tools.js';
+export { createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, } 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.35",
+  "version": "0.10.37",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,10 @@
     "./team/role-aliases": {
       "types": "./dist/team/role-aliases.d.ts",
       "import": "./dist/team/role-aliases.js"
+    },
+    "./flow-runner": {
+      "types": "./dist/flow-runner/index.d.ts",
+      "import": "./dist/flow-runner/index.js"
     }
   },
   "files": [