@bradygaster/squad-sdk 0.7.0 → 0.8.2

package/dist/agents/lifecycle.js

@@ -0,0 +1,284 @@
+/**
+ * Agent Session Lifecycle (M1-7)
+ *
+ * Orchestrates the complete lifecycle of agent sessions:
+ * - Spawning: charter compilation, model selection, session creation
+ * - Management: status tracking, message handling
+ * - Destruction: graceful shutdown and history saving
+ */
+import { compileCharter } from './charter-compiler.js';
+import { resolveModel } from './model-selector.js';
+import { ConfigurationError, SessionLifecycleError } from '../adapter/errors.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { recordAgentSpawn, recordAgentDestroy, recordAgentError } from '../runtime/otel-metrics.js';
+const tracer = trace.getTracer('squad-sdk');
+/**
+ * Manages the full lifecycle of agent sessions.
+ *
+ * Coordinates charter compilation, model selection, session creation,
+ * and graceful shutdown with history persistence.
+ */
+export class AgentLifecycleManager {
+    client;
+    teamRoot;
+    defaultIdleTimeout;
+    agents = new Map();
+    idleCheckTimer = null;
+    constructor(config) {
+        this.client = config.client;
+        this.teamRoot = config.teamRoot;
+        this.defaultIdleTimeout = config.defaultIdleTimeout ?? 300_000; // 5 minutes
+        // Start idle timeout checker
+        this.startIdleChecker();
+    }
+    /**
+     * Spawn a new agent with full lifecycle setup.
+     *
+     * Pipeline:
+     * 1. Read charter.md from team root
+     * 2. Compile charter with team context
+     * 3. Resolve model using 4-layer priority
+     * 4. Create session via Squad Client
+     * 5. Set up event handlers
+     * 6. Return AgentHandle
+     *
+     * @param options - Spawn options
+     * @returns Agent handle for control and communication
+     */
+    async spawnAgent(options) {
+        const span = tracer.startSpan('squad.lifecycle.spawnAgent');
+        span.setAttribute('agent.name', options.agentName);
+        span.setAttribute('task.type', options.taskType ?? 'code');
+        const { agentName, task, taskType = 'code', modelOverride, teamContext, routingRules, decisions, idleTimeout = this.defaultIdleTimeout, } = options;
+        try {
+            // Step 1: Read charter.md
+            const charterPath = path.join(this.teamRoot, '.ai-team', 'agents', agentName, 'charter.md');
+            let charterContent;
+            try {
+                charterContent = await fs.readFile(charterPath, 'utf-8');
+            }
+            catch (error) {
+                throw new ConfigurationError(`Charter not found for agent '${agentName}' at ${charterPath}`, {
+                    agentName,
+                    operation: 'spawnAgent',
+                    timestamp: new Date(),
+                    metadata: { charterPath },
+                }, error instanceof Error ? error : undefined);
+            }
+            // Step 2: Compile charter
+            const compileOptions = {
+                agentName,
+                charterPath,
+                teamContext,
+                routingRules,
+                decisions,
+            };
+            const agentConfig = compileCharter(compileOptions);
+            // Step 3: Resolve model
+            const modelOptions = {
+                userOverride: modelOverride,
+                charterPreference: agentConfig.prompt.includes('## Model')
+                    ? this.extractModelPreference(charterContent)
+                    : undefined,
+                taskType,
+                agentRole: agentName,
+            };
+            const resolvedModel = resolveModel(modelOptions);
+            // Step 4: Create session
+            const sessionConfig = {
+                model: resolvedModel.model,
+                systemMessage: {
+                    content: agentConfig.prompt,
+                },
+            };
+            const session = await this.client.createSession(sessionConfig);
+            // Step 5: Create handle with event handlers
+            const handle = new AgentHandleImpl({
+                agentName,
+                sessionId: session.sessionId,
+                model: resolvedModel.model,
+                session,
+                idleTimeout,
+                onDestroy: () => this.agents.delete(session.sessionId),
+            });
+            this.agents.set(session.sessionId, handle);
+            recordAgentSpawn(agentName, 'lifecycle');
+            // Step 6: Send initial task
+            await handle.sendMessage(task);
+            return handle;
+        }
+        catch (error) {
+            recordAgentError(agentName, error instanceof Error ? error.constructor.name : 'unknown');
+            span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) });
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            throw new SessionLifecycleError(`Failed to spawn agent '${agentName}': ${error instanceof Error ? error.message : String(error)}`, {
+                agentName,
+                operation: 'spawnAgent',
+                timestamp: new Date(),
+            }, false, error instanceof Error ? error : undefined);
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Destroy an agent gracefully.
+     * Saves history and cleans up session.
+     *
+     * @param handle - Agent handle to destroy
+     */
+    async destroyAgent(handle) {
+        const span = tracer.startSpan('squad.lifecycle.destroyAgent');
+        span.setAttribute('agent.name', handle.agentName);
+        try {
+            await handle.destroy();
+            this.agents.delete(handle.sessionId);
+            recordAgentDestroy(handle.agentName);
+        }
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+            span.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * List all active agent sessions.
+     *
+     * @returns Array of active agent handles
+     */
+    listActive() {
+        return Array.from(this.agents.values()).filter(agent => agent.status !== 'destroyed');
+    }
+    /**
+     * Get agent handle by session ID.
+     *
+     * @param sessionId - Session ID to look up
+     * @returns Agent handle or undefined
+     */
+    getAgent(sessionId) {
+        return this.agents.get(sessionId);
+    }
+    /**
+     * Shutdown all agents gracefully.
+     */
+    async shutdown() {
+        if (this.idleCheckTimer) {
+            clearInterval(this.idleCheckTimer);
+            this.idleCheckTimer = null;
+        }
+        const destroyPromises = Array.from(this.agents.values()).map(agent => agent.destroy().catch(err => {
+            console.error(`Failed to destroy agent ${agent.agentName}:`, err);
+        }));
+        await Promise.all(destroyPromises);
+        this.agents.clear();
+    }
+    /**
+     * Start periodic idle timeout checker.
+     * @private
+     */
+    startIdleChecker() {
+        this.idleCheckTimer = setInterval(() => {
+            const now = Date.now();
+            for (const agent of this.agents.values()) {
+                const idleTimeMs = now - agent.lastActivityAt.getTime();
+                if (idleTimeMs > this.defaultIdleTimeout && agent.status === 'active') {
+                    agent.markIdle();
+                }
+            }
+        }, 30_000); // Check every 30 seconds
+    }
+    /**
+     * Extract model preference from charter content.
+     * @private
+     */
+    extractModelPreference(charterContent) {
+        const modelMatch = charterContent.match(/##\s+Model\s*\n[\s\S]*?\*\*Preferred:\*\*\s*(.+)/i);
+        return modelMatch ? modelMatch[1].trim() : undefined;
+    }
+}
+/**
+ * Internal implementation of AgentHandle.
+ * @private
+ */
+class AgentHandleImpl {
+    agentName;
+    sessionId;
+    model;
+    status;
+    createdAt;
+    lastActivityAt;
+    session;
+    idleTimeout;
+    onDestroy;
+    constructor(config) {
+        this.agentName = config.agentName;
+        this.sessionId = config.sessionId;
+        this.model = config.model;
+        this.session = config.session;
+        this.idleTimeout = config.idleTimeout;
+        this.onDestroy = config.onDestroy;
+        this.status = 'active';
+        this.createdAt = new Date();
+        this.lastActivityAt = new Date();
+    }
+    async sendMessage(prompt) {
+        if (this.status === 'destroyed') {
+            throw new SessionLifecycleError('Cannot send message to destroyed agent', {
+                agentName: this.agentName,
+                sessionId: this.sessionId,
+                operation: 'sendMessage',
+                timestamp: new Date(),
+            });
+        }
+        try {
+            this.status = 'active';
+            this.lastActivityAt = new Date();
+            // Send message via session
+            await this.session.sendMessage({ prompt });
+        }
+        catch (error) {
+            this.status = 'error';
+            throw new SessionLifecycleError(`Failed to send message to agent '${this.agentName}': ${error instanceof Error ? error.message : String(error)}`, {
+                agentName: this.agentName,
+                sessionId: this.sessionId,
+                operation: 'sendMessage',
+                timestamp: new Date(),
+            }, false, error instanceof Error ? error : undefined);
+        }
+    }
+    async destroy() {
+        if (this.status === 'destroyed') {
+            return;
+        }
+        try {
+            this.status = 'destroyed';
+            // Clean up session
+            await this.session.close();
+            // Notify lifecycle manager
+            this.onDestroy();
+        }
+        catch (error) {
+            throw new SessionLifecycleError(`Failed to destroy agent '${this.agentName}': ${error instanceof Error ? error.message : String(error)}`, {
+                agentName: this.agentName,
+                sessionId: this.sessionId,
+                operation: 'destroy',
+                timestamp: new Date(),
+            }, false, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Mark agent as idle (called by lifecycle manager).
+     * @internal
+     */
+    markIdle() {
+        if (this.status === 'active') {
+            this.status = 'idle';
+        }
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/agents/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/agents/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/agents/model-selector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Per-Agent Model Selection (M1-9) + Model Fallback (M3-5, Issue #145)
+ */
+import type { EventBus } from '../runtime/event-bus.js';
+/**
+ * Task types that influence model selection.
+ */
+export type TaskType = 'code' | 'prompt' | 'docs' | 'visual' | 'planning' | 'mechanical';
+/**
+ * Model tier classification.
+ */
+export type ModelTier = 'premium' | 'standard' | 'fast';
+/**
+ * Source of the model resolution.
+ */
+export type ModelResolutionSource = 'user-override' | 'charter' | 'task-auto' | 'default';
+/**
+ * Options for model resolution.
+ */
+export interface ModelResolutionOptions {
+    /** User-specified model override */
+    userOverride?: string;
+    /** Model preference from agent's charter (## Model section) */
+    charterPreference?: string;
+    /** Type of task being performed */
+    taskType: TaskType;
+    /** Agent role (for context) */
+    agentRole?: string;
+}
+/**
+ * Result of model resolution.
+ */
+export interface ResolvedModel {
+    /** Selected model identifier */
+    model: string;
+    /** Model tier classification */
+    tier: ModelTier;
+    /** Source that determined the model */
+    source: ModelResolutionSource;
+    /** Fallback chain for this tier */
+    fallbackChain: string[];
+}
+/**
+ * Resolve the appropriate model using the 4-layer priority system.
+ *
+ * @param options - Model resolution options
+ * @returns Resolved model with tier and fallback chain
+ */
+export declare function resolveModel(options: ModelResolutionOptions): ResolvedModel;
+export declare function inferTierFromModel(model: string): ModelTier;
+export declare function isTierFallbackAllowed(fromTier: ModelTier, toTier: ModelTier, allowCrossTier: boolean): boolean;
+export interface FallbackAttempt {
+    model: string;
+    tier: ModelTier;
+    error: string;
+    timestamp: Date;
+}
+export interface FallbackResult<T> {
+    value: T;
+    model: string;
+    tier: ModelTier;
+    attempts: FallbackAttempt[];
+    didFallback: boolean;
+}
+export interface FallbackExecutorConfig {
+    allowCrossTier?: boolean;
+    eventBus?: EventBus;
+}
+export declare class ModelFallbackExecutor {
+    private allowCrossTier;
+    private eventBus?;
+    private history;
+    constructor(config?: FallbackExecutorConfig);
+    execute<T>(resolved: ResolvedModel, agentName: string, fn: (model: string) => Promise<T>): Promise<FallbackResult<T>>;
+    getHistory(agentName: string): FallbackAttempt[];
+    clearHistory(): void;
+    private buildCandidateList;
+    private emitEvent;
+}
+//# sourceMappingURL=model-selector.d.ts.map

package/dist/agents/model-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selector.d.ts","sourceRoot":"","sources":["../../src/agents/model-selector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,uCAAuC;IACvC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,mCAAmC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa,CAsC3E;AAiDD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAa3D;AAQD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,OAAO,GACtB,OAAO,CAIT;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,OAAO,CAA6C;gBAEhD,MAAM,GAAE,sBAA2B;IAKzC,OAAO,CAAC,CAAC,EACb,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA6B7B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE;IAIhD,YAAY,IAAI,IAAI;IAIpB,OAAO,CAAC,kBAAkB;YASZ,SAAS;CAIxB"}

package/dist/agents/model-selector.js

@@ -0,0 +1,171 @@
+/**
+ * Per-Agent Model Selection (M1-9) + Model Fallback (M3-5, Issue #145)
+ */
+import { MODELS } from '../runtime/constants.js';
+/**
+ * Resolve the appropriate model using the 4-layer priority system.
+ *
+ * @param options - Model resolution options
+ * @returns Resolved model with tier and fallback chain
+ */
+export function resolveModel(options) {
+    const { userOverride, charterPreference, taskType } = options;
+    // Layer 1: User Override
+    if (userOverride && userOverride.trim().length > 0) {
+        const tier = inferTierFromModel(userOverride);
+        return {
+            model: userOverride,
+            tier,
+            source: 'user-override',
+            fallbackChain: [...MODELS.FALLBACK_CHAINS[tier]],
+        };
+    }
+    // Layer 2: Charter Preference
+    if (charterPreference && charterPreference.trim().length > 0 && charterPreference !== 'auto') {
+        const tier = inferTierFromModel(charterPreference);
+        return {
+            model: charterPreference,
+            tier,
+            source: 'charter',
+            fallbackChain: [...MODELS.FALLBACK_CHAINS[tier]],
+        };
+    }
+    // Layer 3: Task-Aware Auto-Selection
+    const autoSelected = selectModelForTask(taskType);
+    if (autoSelected) {
+        return autoSelected;
+    }
+    // Layer 4: Default
+    return {
+        model: MODELS.SELECTOR_DEFAULT,
+        tier: MODELS.SELECTOR_DEFAULT_TIER,
+        source: 'default',
+        fallbackChain: [...MODELS.FALLBACK_CHAINS[MODELS.SELECTOR_DEFAULT_TIER]],
+    };
+}
+/**
+ * Select model based on task type.
+ *
+ * @param taskType - Type of task being performed
+ * @returns Resolved model or undefined if no match
+ */
+function selectModelForTask(taskType) {
+    switch (taskType) {
+        case 'code':
+            return {
+                model: 'claude-sonnet-4.5',
+                tier: 'standard',
+                source: 'task-auto',
+                fallbackChain: [...MODELS.FALLBACK_CHAINS.standard],
+            };
+        case 'prompt':
+            return {
+                model: 'claude-sonnet-4.5',
+                tier: 'standard',
+                source: 'task-auto',
+                fallbackChain: [...MODELS.FALLBACK_CHAINS.standard],
+            };
+        case 'visual':
+            return {
+                model: 'claude-opus-4.5',
+                tier: 'premium',
+                source: 'task-auto',
+                fallbackChain: [...MODELS.FALLBACK_CHAINS.premium],
+            };
+        case 'docs':
+        case 'planning':
+        case 'mechanical':
+            return {
+                model: 'claude-haiku-4.5',
+                tier: 'fast',
+                source: 'task-auto',
+                fallbackChain: [...MODELS.FALLBACK_CHAINS.fast],
+            };
+        default:
+            return undefined;
+    }
+}
+export function inferTierFromModel(model) {
+    const lowerModel = model.toLowerCase();
+    if (lowerModel.includes('opus')) {
+        return 'premium';
+    }
+    if (lowerModel.includes('haiku') || lowerModel.includes('mini')) {
+        return 'fast';
+    }
+    // Default to standard for sonnet, gpt-5.x, etc.
+    return 'standard';
+}
+// ============================================================================
+// Model Fallback Executor (M3-5, Issue #145)
+// ============================================================================
+const TIER_ORDER = { premium: 0, standard: 1, fast: 2 };
+export function isTierFallbackAllowed(fromTier, toTier, allowCrossTier) {
+    if (allowCrossTier)
+        return true;
+    if (fromTier === toTier)
+        return true;
+    return TIER_ORDER[toTier] <= TIER_ORDER[fromTier];
+}
+export class ModelFallbackExecutor {
+    allowCrossTier;
+    eventBus;
+    history = new Map();
+    constructor(config = {}) {
+        this.allowCrossTier = config.allowCrossTier ?? false;
+        this.eventBus = config.eventBus;
+    }
+    async execute(resolved, agentName, fn) {
+        const attempts = [];
+        const originalTier = resolved.tier;
+        const candidates = this.buildCandidateList(resolved);
+        for (const candidate of candidates) {
+            const candidateTier = inferTierFromModel(candidate);
+            if (!isTierFallbackAllowed(originalTier, candidateTier, this.allowCrossTier)) {
+                continue;
+            }
+            try {
+                const value = await fn(candidate);
+                if (!this.history.has(agentName))
+                    this.history.set(agentName, []);
+                this.history.get(agentName).push(...attempts);
+                return { value, model: candidate, tier: candidateTier, attempts, didFallback: attempts.length > 0 };
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                const attempt = { model: candidate, tier: candidateTier, error: errorMsg, timestamp: new Date() };
+                attempts.push(attempt);
+                await this.emitEvent('agent:milestone', { event: 'model.fallback', agentName, failedModel: candidate, failedTier: candidateTier, error: errorMsg, attemptNumber: attempts.length });
+            }
+        }
+        if (!this.history.has(agentName))
+            this.history.set(agentName, []);
+        this.history.get(agentName).push(...attempts);
+        await this.emitEvent('agent:milestone', { event: 'model.exhausted', agentName, originalModel: resolved.model, originalTier, totalAttempts: attempts.length });
+        throw new Error(`All models exhausted for agent '${agentName}'. Tried ${attempts.length} model(s): ${attempts.map(a => a.model).join(', ')}`);
+    }
+    getHistory(agentName) {
+        return this.history.get(agentName) ?? [];
+    }
+    clearHistory() {
+        this.history.clear();
+    }
+    buildCandidateList(resolved) {
+        const seen = new Set();
+        const result = [];
+        const add = (m) => { if (!seen.has(m)) {
+            seen.add(m);
+            result.push(m);
+        } };
+        add(resolved.model);
+        for (const fb of resolved.fallbackChain)
+            add(fb);
+        return result;
+    }
+    async emitEvent(type, payload) {
+        if (!this.eventBus)
+            return;
+        await this.eventBus.emit({ type: type, payload, timestamp: new Date() });
+    }
+}
+//# sourceMappingURL=model-selector.js.map

package/dist/agents/model-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selector.js","sourceRoot":"","sources":["../../src/agents/model-selector.ts"],"names":[],"mappings":"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"}

package/dist/agents/onboarding.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent Onboarding Module (M2-10, PRD #111)
+ *
+ * Handles runtime agent onboarding with context-aware charter generation.
+ * Creates agent directory, charter, and history with project context.
+ *
+ * @module agents/onboarding
+ */
+/**
+ * Agent onboarding options.
+ */
+export interface OnboardOptions {
+    /** Root directory for Squad team files */
+    teamRoot: string;
+    /** Agent name (kebab-case) */
+    agentName: string;
+    /** Agent role identifier */
+    role: string;
+    /** Display name (optional, defaults to titlecased name) */
+    displayName?: string;
+    /** Project context for charter generation */
+    projectContext?: string;
+    /** User name for initial history entry */
+    userName?: string;
+    /** Custom charter template override */
+    charterTemplate?: string;
+}
+/**
+ * Agent onboarding result.
+ */
+export interface OnboardResult {
+    /** Created file paths */
+    createdFiles: string[];
+    /** Agent directory path */
+    agentDir: string;
+    /** Charter file path */
+    charterPath: string;
+    /** History file path */
+    historyPath: string;
+}
+/**
+ * Onboard a new agent to the Squad.
+ *
+ * Creates:
+ * - Agent directory at .squad/agents/{name}/
+ * - charter.md from role template + project context
+ * - history.md with project description and tech stack
+ *
+ * @param options - Onboarding options
+ * @returns Result with created file paths
+ */
+export declare function onboardAgent(options: OnboardOptions): Promise<OnboardResult>;
+/**
+ * Update an agent's configuration to squad.config.ts (if it exists).
+ *
+ * This is a helper function to add agent routing after onboarding.
+ * Only works with TypeScript configs (JSON requires manual edit).
+ *
+ * @param teamRoot - Team root directory
+ * @param agentName - Agent name to add
+ * @param role - Agent role
+ * @returns True if config was updated, false if not found or JSON format
+ */
+export declare function addAgentToConfig(teamRoot: string, agentName: string, role: string): Promise<boolean>;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/agents/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/agents/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAoQD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA2ElF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAwDlB"}