@compilr-dev/sdk 0.10.17 → 0.10.18

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, } 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, 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, } 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,5 @@ 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';

package/dist/team/index.js

@@ -33,3 +33,6 @@ 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';

package/package.json

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