@compilr-dev/sdk 0.1.28 → 0.2.1

package/dist/agent.js

@@ -29,17 +29,27 @@ function toRunResult(raw) {
     };
 }
 /**
- * Build permission manager options from config
+ * Build permission manager options from config.
+ *
+ * When a PermissionCallback is provided:
+ * - defaultLevel is 'always' (tools auto-allowed unless rules say otherwise)
+ * - includeDefaults is true (agents library's built-in rules for dangerous tools)
+ * - Custom rules can be passed via permissionRules
+ *
+ * This matches the CLI pattern: everything allowed by default, only dangerous
+ * tools (bash, write_file, edit, etc.) require user approval.
  */
-function buildPermissions(permissions, presetDefault) {
+function buildPermissions(permissions, presetDefault, permissionRules, includeDefaultRules) {
     const mode = permissions ?? presetDefault ?? 'auto';
     if (mode === 'read-only') {
         return { defaultLevel: 'deny' };
     }
     if (typeof mode === 'function') {
         return {
-            defaultLevel: 'once',
+            defaultLevel: 'always',
             onPermissionRequest: mode,
+            rules: permissionRules,
+            includeDefaults: includeDefaultRules ?? true,
         };
     }
     // 'auto' — allow all tools
@@ -102,7 +112,7 @@ class CompilrAgentImpl {
             });
         }
         // Build agent config
-        const permissionsConfig = buildPermissions(config?.permissions, preset.defaultPermissions);
+        const permissionsConfig = buildPermissions(config?.permissions, preset.defaultPermissions, config?.permissionRules, config?.includeDefaultRules);
         const guardrailsConfig = buildGuardrails(config?.guardrails);
         this.agent = new Agent({
             provider,
@@ -114,6 +124,8 @@ class CompilrAgentImpl {
             permissions: {
                 defaultLevel: permissionsConfig.defaultLevel,
                 onPermissionRequest: permissionsConfig.onPermissionRequest,
+                rules: permissionsConfig.rules,
+                includeDefaults: permissionsConfig.includeDefaults,
             },
             guardrails: {
                 enabled: guardrailsConfig.enabled,

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * SDK configuration types
  */
-import type { LLMProvider, Message, Tool, HooksConfig, AnchorInput, AgentEvent, ToolExecutionResult } from '@compilr-dev/agents';
+import type { LLMProvider, Message, Tool, ToolPermission, HooksConfig, AnchorInput, AgentEvent, ToolExecutionResult } from '@compilr-dev/agents';
 import type { Preset } from './presets/types.js';
 /**
  * Supported provider types for auto-detection
@@ -128,6 +128,17 @@ export interface CompilrAgentConfig {
     tools?: ToolConfig;
     /** Permission mode. Default: 'auto' */
     permissions?: 'auto' | 'read-only' | PermissionCallback;
+    /**
+     * Tool-specific permission rules (e.g., bash='once', read_file='always').
+     * When omitted with a PermissionCallback, the agents library's built-in
+     * defaults are used (includeDefaults: true).
+     */
+    permissionRules?: ToolPermission[];
+    /**
+     * Whether to include the agents library's built-in default permission rules.
+     * Default: true when a PermissionCallback is provided, false otherwise.
+     */
+    includeDefaultRules?: boolean;
     /** Guardrail configuration. Default: true */
     guardrails?: boolean | GuardrailConfig;
     /** Lifecycle hooks */

package/dist/index.d.ts

@@ -34,8 +34,12 @@
  * ```
  */
 export { createCompilrAgent } from './agent.js';
-export { createTeam } from './team.js';
-export type { CompilrAgentConfig, CompilrAgent, CompilrTeam, RunOptions, RunResult, ToolCallRecord, ToolConfig, TeamConfig, TeamAgentConfig, TeamResult, TeamEvent, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, } from './config.js';
+export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, } from './config.js';
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, } from './team/index.js';
+export type { AgentTeamConfig, TeamAgentConfig, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, 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 { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, } from './team/index.js';
+export { getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, 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';
 export type { Preset } from './presets/index.js';
 export type { AnyTool } from './presets/types.js';

package/dist/index.js

@@ -37,7 +37,33 @@
 // Core API
 // =============================================================================
 export { createCompilrAgent } from './agent.js';
-export { createTeam } from './team.js';
+// =============================================================================
+// Multi-Agent Team Orchestration
+// =============================================================================
+// Core classes
+export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, } from './team/index.js';
+// Constants
+export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, } from './team/index.js';
+// Utility functions
+export { 
+// Tool config
+getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, 
+// Tool config (extended)
+createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, 
+// Custom agents
+assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, 
+// Mention parsing
+parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, buildContextMap, 
+// Agent selection
+findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, 
+// Task management
+suggestOwner, suggestOwners, matchesAgentExpertise, wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, 
+// Delegation
+resolveAgentIdCollision, 
+// Activity
+setActiveSharedContext, getActiveSharedContext, recordTeamActivity, 
+// Skills
+getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
 // =============================================================================
 // Presets
 // =============================================================================

package/dist/team/activity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Activity Recording Module
+ *
+ * Provides a global function for tools to record team activity.
+ * The SharedContextManager is set by the consumer when a team is active.
+ */
+import type { SharedContextManager, TeamActivityType } from './shared-context.js';
+/**
+ * Set the active SharedContextManager for activity recording
+ * Called by the consumer when a team is initialized
+ */
+export declare function setActiveSharedContext(ctx: SharedContextManager | null): void;
+/**
+ * Get the active SharedContextManager
+ */
+export declare function getActiveSharedContext(): SharedContextManager | null;
+/**
+ * Record team activity
+ * Safe to call even if no team is active (will be a no-op)
+ */
+export declare function recordTeamActivity(agentId: string, action: TeamActivityType, summary: string): void;

package/dist/team/activity.js

@@ -0,0 +1,34 @@
+/**
+ * Activity Recording Module
+ *
+ * Provides a global function for tools to record team activity.
+ * The SharedContextManager is set by the consumer when a team is active.
+ */
+// Module-level reference to the active SharedContextManager
+let activeSharedContext = null;
+/**
+ * Set the active SharedContextManager for activity recording
+ * Called by the consumer when a team is initialized
+ */
+export function setActiveSharedContext(ctx) {
+    activeSharedContext = ctx;
+}
+/**
+ * Get the active SharedContextManager
+ */
+export function getActiveSharedContext() {
+    return activeSharedContext;
+}
+/**
+ * Record team activity
+ * Safe to call even if no team is active (will be a no-op)
+ */
+export function recordTeamActivity(agentId, action, summary) {
+    if (activeSharedContext) {
+        activeSharedContext.recordActivity({
+            agentId,
+            action,
+            summary,
+        });
+    }
+}

package/dist/team/agent-selection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent Selection Helpers
+ *
+ * Provides functions for selecting the best agent for a task:
+ * - findAgentForRole: Find an agent by role (LRU selection if multiple)
+ * - findAgentById: Find an agent by ID
+ * - getAvailableSpecialists: Get all non-default agents
+ *
+ * Uses Least Recently Used (LRU) selection when multiple agents have the same role.
+ */
+import type { AgentTeam } from './team.js';
+import type { TeamAgent } from './team-agent.js';
+import type { AgentRole } from './types.js';
+/**
+ * Find the best agent for a given role.
+ * If multiple agents have the same role, selects the least recently used.
+ *
+ * @param team - The agent team
+ * @param role - The role to find (e.g., 'arch', 'dev', 'qa')
+ * @returns The best matching agent, or null if none found
+ */
+export declare function findAgentForRole(team: AgentTeam, role: AgentRole): TeamAgent | null;
+/**
+ * Find an agent by ID.
+ *
+ * @param team - The agent team
+ * @param id - The agent ID (e.g., 'arch', 'dev-1', 'my-custom-agent')
+ * @returns The agent, or null if not found
+ */
+export declare function findAgentById(team: AgentTeam, id: string): TeamAgent | null;
+/**
+ * Get all specialist agents (non-default agents).
+ * Useful for listing available delegation targets.
+ *
+ * @param team - The agent team
+ * @returns Array of specialist agents
+ */
+export declare function getAvailableSpecialists(team: AgentTeam): TeamAgent[];
+/**
+ * Get a summary of available specialists for the coordinator.
+ * Returns a formatted string listing specialists by role.
+ *
+ * @param team - The agent team
+ * @returns Formatted string of available specialists
+ */
+export declare function getSpecialistsSummary(team: AgentTeam): string;
+/**
+ * Check if the team has any specialists available for delegation.
+ *
+ * @param team - The agent team
+ * @returns True if there are specialist agents
+ */
+export declare function hasSpecialists(team: AgentTeam): boolean;

package/dist/team/agent-selection.js

@@ -0,0 +1,88 @@
+/**
+ * Agent Selection Helpers
+ *
+ * Provides functions for selecting the best agent for a task:
+ * - findAgentForRole: Find an agent by role (LRU selection if multiple)
+ * - findAgentById: Find an agent by ID
+ * - getAvailableSpecialists: Get all non-default agents
+ *
+ * Uses Least Recently Used (LRU) selection when multiple agents have the same role.
+ */
+/**
+ * Find the best agent for a given role.
+ * If multiple agents have the same role, selects the least recently used.
+ *
+ * @param team - The agent team
+ * @param role - The role to find (e.g., 'arch', 'dev', 'qa')
+ * @returns The best matching agent, or null if none found
+ */
+export function findAgentForRole(team, role) {
+    const agents = team.getAll();
+    // Filter to agents with matching role
+    const candidates = agents.filter((agent) => agent.role === role);
+    if (candidates.length === 0) {
+        return null;
+    }
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    // Multiple candidates: select Least Recently Used (LRU)
+    // Sort by lastActivity ascending (oldest first)
+    candidates.sort((a, b) => a.lastActivity.getTime() - b.lastActivity.getTime());
+    return candidates[0];
+}
+/**
+ * Find an agent by ID.
+ *
+ * @param team - The agent team
+ * @param id - The agent ID (e.g., 'arch', 'dev-1', 'my-custom-agent')
+ * @returns The agent, or null if not found
+ */
+export function findAgentById(team, id) {
+    return team.get(id) ?? null;
+}
+/**
+ * Get all specialist agents (non-default agents).
+ * Useful for listing available delegation targets.
+ *
+ * @param team - The agent team
+ * @returns Array of specialist agents
+ */
+export function getAvailableSpecialists(team) {
+    return team.getAll().filter((agent) => agent.id !== 'default');
+}
+/**
+ * Get a summary of available specialists for the coordinator.
+ * Returns a formatted string listing specialists by role.
+ *
+ * @param team - The agent team
+ * @returns Formatted string of available specialists
+ */
+export function getSpecialistsSummary(team) {
+    const specialists = getAvailableSpecialists(team);
+    if (specialists.length === 0) {
+        return 'No specialist agents available. Add agents via /team.';
+    }
+    // Group by role
+    const byRole = new Map();
+    for (const agent of specialists) {
+        const list = byRole.get(agent.role) ?? [];
+        list.push(agent);
+        byRole.set(agent.role, list);
+    }
+    const lines = [];
+    for (const [role, agents] of byRole) {
+        const agentList = agents.map((a) => `$${a.id}`).join(', ');
+        lines.push(`- ${role}: ${agentList}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Check if the team has any specialists available for delegation.
+ *
+ * @param team - The agent team
+ * @returns True if there are specialist agents
+ */
+export function hasSpecialists(team) {
+    return getAvailableSpecialists(team).length > 0;
+}

package/dist/team/artifacts.d.ts

@@ -0,0 +1,175 @@
+/**
+ * ArtifactStore - Storage for team artifacts
+ *
+ * Artifacts are named pieces of work that agents can publish and reference:
+ * - design: Architecture, API specs, data models
+ * - plan: Sprint plans, task breakdowns, timelines
+ * - review: Code reviews, security audits, feedback
+ * - decision: Architectural decisions, trade-off analysis
+ * - note: General notes, meeting summaries
+ */
+/**
+ * Artifact types
+ */
+export type ArtifactType = 'design' | 'plan' | 'review' | 'decision' | 'note';
+/**
+ * Full artifact structure
+ */
+export interface Artifact {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary: string;
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+    mentions: string[];
+    referencedBy: string[];
+}
+/**
+ * Artifact summary for the shared context index
+ */
+export interface ArtifactSummary {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    summary: string;
+    updatedAt: Date;
+}
+/**
+ * Options for creating an artifact
+ */
+export interface CreateArtifactOptions {
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary?: string;
+}
+/**
+ * Options for updating an artifact
+ */
+export interface UpdateArtifactOptions {
+    content?: string;
+    summary?: string;
+    type?: ArtifactType;
+}
+/**
+ * Serialized artifact for persistence
+ */
+export interface SerializedArtifact {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    mentions?: string[];
+    referencedBy?: string[];
+}
+/**
+ * Artifact index for persistence
+ */
+export interface ArtifactIndex {
+    version: number;
+    artifacts: Array<{
+        id: string;
+        name: string;
+        agent: string;
+        type: ArtifactType;
+        summary: string;
+        updatedAt: string;
+    }>;
+    updatedAt: string;
+}
+/**
+ * Manages artifact storage and retrieval
+ */
+export declare class ArtifactStore {
+    private readonly artifacts;
+    private readonly nameToId;
+    private updatedAt;
+    /**
+     * Create a new artifact
+     */
+    create(options: CreateArtifactOptions): Artifact;
+    /**
+     * Get an artifact by ID
+     */
+    get(id: string): Artifact | undefined;
+    /**
+     * Get an artifact by name (case-insensitive)
+     */
+    getByName(name: string): Artifact | undefined;
+    /**
+     * Update an artifact
+     */
+    update(id: string, options: UpdateArtifactOptions): Artifact | undefined;
+    /**
+     * Delete an artifact
+     */
+    delete(id: string): boolean;
+    /**
+     * Rename an artifact
+     */
+    rename(id: string, newName: string): Artifact | undefined;
+    /**
+     * List all artifacts
+     */
+    list(): Artifact[];
+    /**
+     * List artifacts by agent
+     */
+    listByAgent(agent: string): Artifact[];
+    /**
+     * List artifacts by type
+     */
+    listByType(type: ArtifactType): Artifact[];
+    /**
+     * Search artifacts by name or content
+     */
+    search(query: string): Artifact[];
+    /**
+     * Get artifact count
+     */
+    get size(): number;
+    /**
+     * Check if an artifact exists by name
+     */
+    has(name: string): boolean;
+    /**
+     * Check if an artifact exists by ID
+     */
+    hasId(id: string): boolean;
+    /**
+     * Generate a summary from content
+     * Simple extraction of first meaningful lines
+     */
+    private generateSummary;
+    /**
+     * Get summaries for shared context injection
+     */
+    getSummaries(): ArtifactSummary[];
+    /**
+     * Serialize all artifacts for external persistence
+     */
+    serialize(): SerializedArtifact[];
+    /**
+     * Restore artifacts from serialized data
+     */
+    restore(data: SerializedArtifact[]): void;
+    /**
+     * Clear all artifacts
+     */
+    clear(): void;
+    /**
+     * Get the last update timestamp
+     */
+    getLastUpdated(): Date;
+}