@compilr-dev/sdk 0.10.19 → 0.10.21

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

@@ -0,0 +1,103 @@
+/**
+ * Consult Tool — Specialist-to-Specialist Sync Borrow
+ *
+ * Fills the gap in the multi-agent tool set where a specialist needs a
+ * focused answer from another specialist without giving up the conversation.
+ *
+ * Symmetric tool set:
+ *
+ *  | Caller       | Sync         | Async                  | Transfer  |
+ *  |--------------|--------------|------------------------|-----------|
+ *  | Coordinator  | `delegate`   | `delegate_background`  | —         |
+ *  | Specialist   | `consult`    | (deferred)             | `handoff` |
+ *
+ * Loop-impossible by construction: the borrower blocks waiting for the
+ * target's response and never yields control. No chain state, no hop
+ * counter, no one-hop rule needed. Each agent's run is bounded by its
+ * existing max-iterations cap, and the call stack unwinds naturally if
+ * the target itself consults a third agent.
+ *
+ * Spec:
+ *   /workspace/project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
+ */
+import { type Tool } from '@compilr-dev/agents';
+import type { AgentTeam } from './team.js';
+export interface ConsultInput {
+    agentId: string;
+    question: string;
+    context?: string;
+}
+/**
+ * Result the platform's `onConsult` handler hands back to the tool.
+ * Identical shape to what the LLM sees, with an optional error path.
+ */
+export interface ConsultResult {
+    /** Final response text from the target agent. */
+    answer: string;
+    /** Target agent ID (echoed back for the LLM's benefit). */
+    agentId: string;
+    /** Error message if the consult failed at the platform layer
+     *  (target run exceeded max iterations, transport error, etc.). */
+    error?: string;
+}
+/**
+ * Configuration for `createConsultTool`.
+ *
+ * `onConsult` is intentionally platform-shaped — each host runs sub-agents
+ * differently (CLI's REPL sub-context, Desktop's agent-manager, in-process
+ * Agent.run). The SDK owns validation and message format; the platform
+ * owns the actual run.
+ */
+export interface ConsultToolConfig {
+    /** The team instance — used to validate target agent membership. */
+    team: AgentTeam;
+    /** The borrowing agent's ID. */
+    currentAgentId: string;
+    /**
+     * Platform-specific consult handler. Called after validation passes.
+     * Should:
+     *   1. Synthesise the question message (use `buildConsultQuestionMessage`).
+     *   2. Run the target agent against that message (sub-run, not a turn
+     *      in the borrower's conversation).
+     *   3. Return the target's final response text.
+     *
+     * The target's conversation history is NOT mutated by a consult — the
+     * call is transient.
+     */
+    onConsult: (targetAgentId: string, question: string, context: string | undefined) => Promise<{
+        answer: string;
+        error?: string;
+    }>;
+}
+/**
+ * Build the synthesised message handed to the target agent. The
+ * `[Consult from $X]` marker keeps the target oriented and gives future
+ * tooling a way to distinguish consult sub-runs from direct user input or
+ * handoff-injected turns.
+ *
+ * Format:
+ *
+ *     [Consult from $arch]
+ *
+ *     Question: <verbatim question>
+ *
+ *     Context:
+ *     <verbatim context>     (whole block omitted when absent)
+ */
+export declare function buildConsultQuestionMessage(input: {
+    sourceAgentId: string;
+    question: string;
+    context?: string;
+}): string;
+/**
+ * Create a `consult` tool bound to a specific borrowing agent.
+ *
+ * Validation rules (enforced before `onConsult` fires):
+ *   1. `agentId` and `question` are non-empty strings.
+ *   2. Target agent exists in the team.
+ *   3. Target is not the borrower itself.
+ *   4. Target is not `default` — specialists escalate to the coordinator
+ *      via `handoff`, not `consult`. (Coordinators have `delegate` for the
+ *      same semantic in the other direction.)
+ */
+export declare function createConsultTool(config: ConsultToolConfig): Tool<ConsultInput>;

package/dist/team/consult-tool.js

@@ -0,0 +1,142 @@
+/**
+ * Consult Tool — Specialist-to-Specialist Sync Borrow
+ *
+ * Fills the gap in the multi-agent tool set where a specialist needs a
+ * focused answer from another specialist without giving up the conversation.
+ *
+ * Symmetric tool set:
+ *
+ *  | Caller       | Sync         | Async                  | Transfer  |
+ *  |--------------|--------------|------------------------|-----------|
+ *  | Coordinator  | `delegate`   | `delegate_background`  | —         |
+ *  | Specialist   | `consult`    | (deferred)             | `handoff` |
+ *
+ * Loop-impossible by construction: the borrower blocks waiting for the
+ * target's response and never yields control. No chain state, no hop
+ * counter, no one-hop rule needed. Each agent's run is bounded by its
+ * existing max-iterations cap, and the call stack unwinds naturally if
+ * the target itself consults a third agent.
+ *
+ * Spec:
+ *   /workspace/project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
+ */
+import { defineTool } from '@compilr-dev/agents';
+// =============================================================================
+// Canonical question-message format
+// =============================================================================
+/**
+ * Build the synthesised message handed to the target agent. The
+ * `[Consult from $X]` marker keeps the target oriented and gives future
+ * tooling a way to distinguish consult sub-runs from direct user input or
+ * handoff-injected turns.
+ *
+ * Format:
+ *
+ *     [Consult from $arch]
+ *
+ *     Question: <verbatim question>
+ *
+ *     Context:
+ *     <verbatim context>     (whole block omitted when absent)
+ */
+export function buildConsultQuestionMessage(input) {
+    const header = `[Consult from $${input.sourceAgentId}]`;
+    const questionBlock = `Question: ${input.question}`;
+    if (input.context && input.context.trim().length > 0) {
+        return `${header}\n\n${questionBlock}\n\nContext:\n${input.context}`;
+    }
+    return `${header}\n\n${questionBlock}`;
+}
+// =============================================================================
+// Tool factory
+// =============================================================================
+/**
+ * Create a `consult` tool bound to a specific borrowing agent.
+ *
+ * Validation rules (enforced before `onConsult` fires):
+ *   1. `agentId` and `question` are non-empty strings.
+ *   2. Target agent exists in the team.
+ *   3. Target is not the borrower itself.
+ *   4. Target is not `default` — specialists escalate to the coordinator
+ *      via `handoff`, not `consult`. (Coordinators have `delegate` for the
+ *      same semantic in the other direction.)
+ */
+export function createConsultTool(config) {
+    const { team, currentAgentId, onConsult } = config;
+    return defineTool({
+        name: 'consult',
+        description: 'Ask another specialist a focused question and continue the conversation yourself. ' +
+            'Use this when you need a quick opinion or expertise input from a teammate without giving up the conversation. ' +
+            'Unlike handoff, you keep ownership — the target answers and control returns to you. ' +
+            'Example: $arch can consult $pm on scope, get an answer, and continue designing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: {
+                    type: 'string',
+                    description: 'Target specialist agent ID to consult (e.g., "pm", "qa", "dev"). ' +
+                        'Cannot be yourself or "default" (use handoff to escalate to the coordinator).',
+                },
+                question: {
+                    type: 'string',
+                    description: 'The focused question you want answered — be specific.',
+                },
+                context: {
+                    type: 'string',
+                    description: 'Optional supporting material the target needs to answer well ' +
+                        '(code snippet, design constraint, current state, etc.).',
+                },
+            },
+            required: ['agentId', 'question'],
+        },
+        execute: async (input) => {
+            // LLM-supplied JSON may not match the typed schema — validate as if
+            // every field could be missing or whitespace. Matches the handoff
+            // tool's defensive style.
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return { success: false, error: 'agentId is required' };
+            }
+            if (!input.question || input.question.trim().length === 0) {
+                return { success: false, error: 'question is required and cannot be empty' };
+            }
+            const targetId = input.agentId.trim();
+            const question = input.question.trim();
+            const context = input.context?.trim() ?? undefined;
+            if (targetId === currentAgentId) {
+                return { success: false, error: 'Cannot consult yourself.' };
+            }
+            if (targetId === 'default') {
+                return {
+                    success: false,
+                    error: 'Cannot consult $default. To escalate to the coordinator, use `handoff` instead. ' +
+                        '`consult` is for specialist-to-specialist questions only.',
+                };
+            }
+            if (!team.has(targetId)) {
+                const available = team
+                    .getAll()
+                    .map((a) => a.id)
+                    .filter((id) => id !== 'default' && id !== currentAgentId)
+                    .join(', ');
+                return {
+                    success: false,
+                    error: `Agent "${targetId}" not found in team. Available specialists: ${available || '(none)'}`,
+                };
+            }
+            try {
+                const { answer, error } = await onConsult(targetId, question, context);
+                if (error) {
+                    return { success: false, error };
+                }
+                const result = { answer, agentId: targetId };
+                return { success: true, result };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Consult failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+}

package/dist/team/index.d.ts

@@ -42,5 +42,7 @@ 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 { createConsultTool, buildConsultQuestionMessage } from './consult-tool.js';
+export type { ConsultInput, ConsultResult, ConsultToolConfig } from './consult-tool.js';
 export { ROLE_NAME_ALIASES, normalizeRoleName } from './role-aliases.js';
 export type { NormalizedRole } from './role-aliases.js';

package/dist/team/index.js

@@ -36,6 +36,9 @@ 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';
+// Consult tool — specialist-to-specialist sync borrow. See consult-tool.ts
+// header. Spec: project-docs/00-requirements/compilr-dev-sdk/consult-tool-spec.md
+export { createConsultTool, buildConsultQuestionMessage } from './consult-tool.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.

package/package.json

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