@compilr-dev/sdk 0.10.7 → 0.10.9

package/dist/compressors/bash.js

@@ -40,6 +40,27 @@ export function compressBashOutput(command, stdout) {
     // curl / wget (HTTP responses)
     if (cmd.match(/^(curl|wget)\b/))
         return compressCurlOutput(stdout);
+    // GitHub CLI (verbose detail commands — pr/issue view, run view)
+    // List commands (pr list, issue list, run list) are already tabular and compact;
+    // pass them through unchanged.
+    if (cmd.match(/^gh\s+(pr|issue|run)\s+view\b/))
+        return compressGhView(stdout);
+    // Docker
+    // `docker logs` — cap to last N lines (logs blow up the context fast)
+    if (cmd.match(/^docker\s+logs\b/))
+        return compressLogsOutput(stdout);
+    // `docker pull/push/build` — strip noisy progress lines, keep summary
+    if (cmd.match(/^docker\s+(pull|push|build)\b/))
+        return compressDockerProgress(stdout);
+    // `docker ps`, `docker images`, `docker stats` — already tabular and compact, pass through
+    // kubectl
+    // `kubectl logs` — same as docker logs
+    if (cmd.match(/^kubectl\s+logs\b/))
+        return compressLogsOutput(stdout);
+    // `kubectl describe` — verbose, often deeply indented; strip noise + cap repeated events
+    if (cmd.match(/^kubectl\s+describe\b/))
+        return compressKubectlDescribe(stdout);
+    // `kubectl get` — already tabular and compact, pass through
     return null; // No compressor matched
 }
 // ─── Git Status ─────────────────────────────────────────────────────────────
@@ -296,6 +317,208 @@ function compressLsOutput(output) {
     }
     return result.join('\n');
 }
+// ─── GitHub CLI: pr/issue/run view ──────────────────────────────────────────
+/**
+ * Compress `gh pr view`, `gh issue view`, `gh run view` output.
+ *
+ * Strips noise that has zero signal for the agent:
+ *   - HTML comments (often left over from PR/issue templates)
+ *   - Markdown badge images and image-only lines
+ *   - Empty metadata lines (`labels:`, `projects:`, `milestone:` with no value)
+ *   - "🤖 Generated with [Claude Code]" / "Co-Authored-By: ..." footers
+ *     (only the duplicated trailing block — preserves any in-body co-authors
+ *     that appear before the body's last paragraph)
+ *   - The trailing "View this pull request on GitHub: <url>" footer
+ *   - Runs of 3+ blank lines collapsed to a single blank
+ *
+ * Pass-through: keeps title, status, body, labels with values, code blocks.
+ */
+function compressGhView(output) {
+    // Drop HTML comments first (multiline regex)
+    const cleaned = output.replace(/<!--[\s\S]*?-->/g, '');
+    const lines = cleaned.split('\n');
+    const kept = [];
+    let consecutiveBlanks = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Trailing "View this pull request on GitHub: ..." / "View this issue on GitHub: ..."
+        if (/^View this (pull request|issue|workflow run) on GitHub:/i.test(trimmed))
+            continue;
+        // Empty metadata lines: `labels:`, `projects:`, `milestone:`, `assignees:`,
+        // `reviewers:` with no value after the colon.
+        if (/^(labels|projects|milestone|assignees|reviewers|tags):\s*$/i.test(trimmed)) {
+            continue;
+        }
+        // Badge image / image-only markdown lines
+        if (/^\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)$/.test(trimmed))
+            continue; // [![badge](img)](link)
+        if (/^!\[[^\]]*\]\([^)]*\)$/.test(trimmed))
+            continue; // ![alt](img)
+        // Collapse runs of blank lines (max 1 consecutive)
+        if (trimmed === '') {
+            consecutiveBlanks++;
+            if (consecutiveBlanks > 1)
+                continue;
+        }
+        else {
+            consecutiveBlanks = 0;
+        }
+        kept.push(line);
+    }
+    // Strip a trailing "🤖 Generated with [Claude Code]" / "Co-Authored-By:" footer
+    // if it's the last non-blank block. We only strip if it's clearly the tail —
+    // we don't want to lose co-authors that appear inside the body.
+    while (kept.length > 0) {
+        const last = kept[kept.length - 1].trim();
+        if (last === '') {
+            kept.pop();
+            continue;
+        }
+        if (last.startsWith('🤖 Generated with [Claude Code]') || /^Co-Authored-By:/i.test(last)) {
+            kept.pop();
+            continue;
+        }
+        break;
+    }
+    return kept.join('\n');
+}
+// ─── Container logs (docker logs / kubectl logs) ────────────────────────────
+const LOGS_MAX_LINES = 100;
+/**
+ * Cap container logs to the last N lines. Logs typically blow up token
+ * usage fast (a single container can produce thousands of lines), and the
+ * agent almost always wants the tail (most-recent failure / state).
+ *
+ * Drops a single banner line at the top noting how many lines were truncated
+ * so the agent knows the output was clipped.
+ */
+function compressLogsOutput(output) {
+    const lines = output.split('\n');
+    // Don't compress small outputs — the cap is the only thing this compressor does.
+    if (lines.length <= LOGS_MAX_LINES)
+        return output;
+    const truncated = lines.length - LOGS_MAX_LINES;
+    const tail = lines.slice(-LOGS_MAX_LINES);
+    return `... (${String(truncated)} earlier log lines truncated — showing last ${String(LOGS_MAX_LINES)})\n${tail.join('\n')}`;
+}
+// ─── docker pull / push / build (strip progress noise) ──────────────────────
+/**
+ * Strip per-layer progress lines from `docker pull/push/build`. Keeps the
+ * digest / "Status: Image is up to date" / "Successfully built" summary lines.
+ *
+ * Patterns dropped (all common Docker progress chatter):
+ *   - "<hash>: Pulling fs layer"
+ *   - "<hash>: Waiting"
+ *   - "<hash>: Verifying Checksum"
+ *   - "<hash>: Downloading [====>     ] 12.3MB/45.6MB"
+ *   - "<hash>: Pull complete" / "Extracting" / "Download complete"
+ *   - BuildKit progress lines: "#5 [internal] load build context"
+ *   - Build context transfer lines
+ */
+function compressDockerProgress(output) {
+    const lines = output.split('\n');
+    const kept = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Per-layer progress patterns (hash prefix + colon + status)
+        if (/^[a-f0-9]{12}:\s+(Pulling fs layer|Waiting|Verifying Checksum|Download complete|Pull complete|Extracting|Downloading|Pushing|Pushed|Mounted from|Layer already exists|Preparing|Already exists)/i.test(trimmed)) {
+            continue;
+        }
+        // BuildKit transfer lines: "#N transferring context: 1.23MB"
+        if (/^#\d+\s+(transferring|sha256:|extracting|naming to|exporting layers|writing image)/.test(trimmed))
+            continue;
+        // Plain "Downloading [====> ] 12MB/45MB" without hash prefix
+        if (/^\s*Downloading\s+\[/.test(line))
+            continue;
+        kept.push(line);
+    }
+    return kept.join('\n');
+}
+// ─── kubectl describe (collapse indentation noise, dedupe events) ───────────
+/**
+ * Compress `kubectl describe` output. The verbose describe format is highly
+ * indented and includes long Events tables that often duplicate the same
+ * message N times ("Back-off restarting failed container").
+ *
+ * Strategy:
+ *   - Trim trailing whitespace on every line (huge amount of padding)
+ *   - Collapse 3+ consecutive blank lines to a single blank
+ *   - In the Events: section, dedupe identical messages — keep first occurrence
+ *     plus a count of repeats ("(x42)")
+ */
+function compressKubectlDescribe(output) {
+    const lines = output.split('\n');
+    const kept = [];
+    let inEvents = false;
+    let consecutiveBlanks = 0;
+    // Track event message → count (only used inside Events: section)
+    const eventCounts = new Map();
+    const eventOrder = [];
+    for (const line of lines) {
+        const rstripped = line.replace(/\s+$/, '');
+        const trimmed = rstripped.trim();
+        // Section header transitions
+        if (/^Events:\s*$/.test(trimmed)) {
+            inEvents = true;
+            kept.push(rstripped);
+            continue;
+        }
+        if (inEvents && /^\S/.test(rstripped) && !/^Events:/.test(trimmed)) {
+            // A non-indented, non-Events: line means we've left the Events section.
+            // Flush deduped events first.
+            flushEvents(kept, eventCounts, eventOrder);
+            inEvents = false;
+        }
+        if (inEvents) {
+            // Inside Events table — collect by "type + reason + message" (drop timestamp/age columns)
+            // Lines look like:
+            //   "  Type     Reason     Age   From     Message"
+            //   "  ----     ------     ---   ----     -------"
+            //   "  Warning  BackOff    1m    kubelet  Back-off restarting failed container"
+            if (trimmed === '' || /^(Type|----)/.test(trimmed)) {
+                kept.push(rstripped);
+                continue;
+            }
+            // Extract the message (everything after the first 4 whitespace-separated columns)
+            const parts = trimmed.split(/\s{2,}/); // 2+ spaces between columns
+            const key = parts.length > 4 ? parts.slice(-1)[0] : trimmed;
+            const count = eventCounts.get(key) ?? 0;
+            if (count === 0)
+                eventOrder.push(rstripped);
+            eventCounts.set(key, count + 1);
+            continue;
+        }
+        // Collapse runs of blank lines
+        if (trimmed === '') {
+            consecutiveBlanks++;
+            if (consecutiveBlanks > 1)
+                continue;
+        }
+        else {
+            consecutiveBlanks = 0;
+        }
+        kept.push(rstripped);
+    }
+    // Flush any pending events at the end
+    if (inEvents)
+        flushEvents(kept, eventCounts, eventOrder);
+    return kept.join('\n');
+}
+function flushEvents(kept, counts, order) {
+    for (const line of order) {
+        const parts = line.trim().split(/\s{2,}/);
+        const key = parts.length > 4 ? parts.slice(-1)[0] : line.trim();
+        const count = counts.get(key) ?? 1;
+        if (count > 1) {
+            kept.push(`${line}  (x${String(count)})`);
+        }
+        else {
+            kept.push(line);
+        }
+    }
+    counts.clear();
+    order.length = 0;
+}
 // ─── curl / wget ────────────────────────────────────────────────────────────
 function compressCurlOutput(output) {
     const lines = output.split('\n');

package/dist/detection/common.js

@@ -79,6 +79,11 @@ function readGitRemote(projectPath) {
 }
 /**
  * Read description from README.md or COMPILR.md (first non-heading paragraph).
+ *
+ * Skips noise commonly found above the first prose paragraph in auto-generated
+ * READMEs: headings, badge images, HTML comments, block-quote callouts, URL-only
+ * lines, and `**Key**: value` bold-metadata lines (e.g. Lovable's `**URL**: ...`,
+ * v0/Vercel templates with `**Demo**: ...`).
  */
 function readDescription(projectPath) {
     const candidates = ['README.md', 'readme.md', 'COMPILR.md'];
@@ -89,7 +94,7 @@ function readDescription(projectPath) {
         try {
             const content = readFileSync(filePath, 'utf-8');
             const lines = content.split('\n');
-            // Find first non-empty, non-heading line
+            // Find first non-empty, non-heading, non-metadata line
             for (const line of lines) {
                 const trimmed = line.trim();
                 if (!trimmed)
@@ -99,7 +104,13 @@ function readDescription(projectPath) {
                 if (trimmed.startsWith('!['))
                     continue; // badge images
                 if (trimmed.startsWith('<!--'))
-                    continue;
+                    continue; // HTML comments
+                if (trimmed.startsWith('>'))
+                    continue; // block-quote callouts / "Note:" disclaimers
+                if (/^\*\*[\w\s/-]+\*\*\s*:/.test(trimmed))
+                    continue; // bold-key metadata: **URL**: ..., **Live Demo**: ...
+                if (/^https?:\/\/\S+\s*$/.test(trimmed))
+                    continue; // URL-only lines
                 // Found a content line — take up to 200 chars
                 return trimmed.length > 200 ? trimmed.slice(0, 200) + '...' : trimmed;
             }

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.9",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",