@bradygaster/squad-sdk 0.7.0 → 0.8.2

package/dist/agents/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Agent Session Lifecycle (PRD 4)
+ *
+ * Manages the full agent lifecycle: spawn → active → idle → cleanup.
+ * Compiles charter.md files into SDK CustomAgentConfig objects.
+ * Injects dynamic context via session hooks instead of string templates.
+ */
+import { EventBus } from '../client/event-bus.js';
+export { compileCharter, compileCharterFull, parseCharterMarkdown, type CharterCompileOptions, type CharterConfigOverrides, type ParsedCharter, type CompiledCharter, } from './charter-compiler.js';
+export { resolveModel, inferTierFromModel, isTierFallbackAllowed, ModelFallbackExecutor, type ModelResolutionOptions, type ResolvedModel, type TaskType, type ModelTier, type ModelResolutionSource, type FallbackExecutorConfig, type FallbackAttempt, type FallbackResult, } from './model-selector.js';
+export { AgentLifecycleManager, type AgentHandle, type AgentStatus, type SpawnAgentOptions, type LifecycleManagerConfig, } from './lifecycle.js';
+export { createHistoryShadow, appendToHistory, readHistory, shadowExists, deleteHistoryShadow, type HistorySection, type ParsedHistory, } from './history-shadow.js';
+export { onboardAgent, addAgentToConfig, type OnboardOptions, type OnboardResult, } from './onboarding.js';
+export interface AgentCharter {
+    /** Agent name (e.g., 'fenster', 'verbal') */
+    name: string;
+    /** Display name (e.g., 'Fenster — Core Dev') */
+    displayName: string;
+    /** Role description */
+    role: string;
+    /** Expertise areas */
+    expertise: string[];
+    /** Working style */
+    style: string;
+    /** Full charter prompt content */
+    prompt: string;
+    /** Allowed tools for this agent */
+    allowedTools?: string[];
+    /** Excluded tools for this agent */
+    excludedTools?: string[];
+    /** Model preference from charter */
+    modelPreference?: string;
+}
+export type AgentLifecycleState = 'pending' | 'spawning' | 'active' | 'idle' | 'error' | 'destroyed';
+export interface AgentSessionInfo {
+    charter: AgentCharter;
+    sessionId: string | null;
+    state: AgentLifecycleState;
+    createdAt: Date | null;
+    lastActiveAt: Date | null;
+    /** Response mode: lightweight (no history), standard, full */
+    responseMode: 'lightweight' | 'standard' | 'full';
+}
+export declare class CharterCompiler {
+    /**
+     * Load and compile a charter.md file into an AgentCharter.
+     * Parses identity/model sections from markdown.
+     */
+    compile(charterPath: string): Promise<AgentCharter>;
+    /**
+     * Load all charters from the team directory.
+     * Scans .squad/agents/{name}/charter.md, skipping scribe and _alumni.
+     */
+    compileAll(teamRoot: string): Promise<AgentCharter[]>;
+}
+export declare class AgentSessionManager {
+    private agents;
+    private eventBus?;
+    constructor(eventBus?: EventBus);
+    /** Spawn a new agent session from a charter */
+    spawn(charter: AgentCharter, mode?: 'lightweight' | 'standard' | 'full'): Promise<AgentSessionInfo>;
+    /** Resume an existing agent session */
+    resume(agentName: string): Promise<AgentSessionInfo>;
+    /** Get info about a specific agent */
+    getAgent(name: string): AgentSessionInfo | undefined;
+    /** Get all agent session info */
+    getAllAgents(): AgentSessionInfo[];
+    /** Destroy an agent session */
+    destroy(agentName: string): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/agents/index.js

@@ -0,0 +1,183 @@
+/**
+ * Agent Session Lifecycle (PRD 4)
+ *
+ * Manages the full agent lifecycle: spawn → active → idle → cleanup.
+ * Compiles charter.md files into SDK CustomAgentConfig objects.
+ * Injects dynamic context via session hooks instead of string templates.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseCharterMarkdown } from './charter-compiler.js';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { recordAgentSpawn, recordAgentDuration, recordAgentError, recordAgentDestroy } from '../runtime/otel-metrics.js';
+const tracer = trace.getTracer('squad-sdk');
+// --- M1-8 Charter Compilation + M2-9 Config-driven ---
+export { compileCharter, compileCharterFull, parseCharterMarkdown, } from './charter-compiler.js';
+// --- M1-9 Model Selection + M3-5 Model Fallback ---
+export { resolveModel, inferTierFromModel, isTierFallbackAllowed, ModelFallbackExecutor, } from './model-selector.js';
+// --- M1-7 Agent Lifecycle ---
+export { AgentLifecycleManager, } from './lifecycle.js';
+// --- M1-11 History Shadows ---
+export { createHistoryShadow, appendToHistory, readHistory, shadowExists, deleteHistoryShadow, } from './history-shadow.js';
+// --- M2-10 Agent Onboarding ---
+export { onboardAgent, addAgentToConfig, } from './onboarding.js';
+// --- Charter Compiler ---
+export class CharterCompiler {
+    /**
+     * Load and compile a charter.md file into an AgentCharter.
+     * Parses identity/model sections from markdown.
+     */
+    async compile(charterPath) {
+        const content = await readFile(charterPath, 'utf-8');
+        const parsed = parseCharterMarkdown(content);
+        const name = parsed.identity.name ?? basename(dirname(charterPath));
+        const role = parsed.identity.role ?? '';
+        const expertise = parsed.identity.expertise ?? [];
+        const style = parsed.identity.style ?? '';
+        const displayName = `${name} — ${role}`;
+        return {
+            name: name.toLowerCase(),
+            displayName,
+            role,
+            expertise,
+            style,
+            prompt: content,
+            modelPreference: parsed.modelPreference,
+        };
+    }
+    /**
+     * Load all charters from the team directory.
+     * Scans .squad/agents/{name}/charter.md, skipping scribe and _alumni.
+     */
+    async compileAll(teamRoot) {
+        const agentsDir = join(teamRoot, '.squad', 'agents');
+        const entries = await readdir(agentsDir, { withFileTypes: true });
+        const charters = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === 'scribe' || entry.name.startsWith('_'))
+                continue;
+            const charterPath = join(agentsDir, entry.name, 'charter.md');
+            try {
+                charters.push(await this.compile(charterPath));
+            }
+            catch {
+                // Skip agents without a valid charter.md
+            }
+        }
+        return charters;
+    }
+}
+// --- Agent Session Manager ---
+export class AgentSessionManager {
+    agents = new Map();
+    eventBus;
+    constructor(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /** Spawn a new agent session from a charter */
+    async spawn(charter, mode = 'standard') {
+        const span = tracer.startSpan('squad.agent.spawn');
+        span.setAttribute('agent.name', charter.name);
+        span.setAttribute('agent.role', charter.role);
+        span.setAttribute('spawn.mode', mode);
+        try {
+            const now = new Date();
+            const info = {
+                charter,
+                sessionId: randomUUID(),
+                state: 'active',
+                createdAt: now,
+                lastActiveAt: now,
+                responseMode: mode,
+            };
+            this.agents.set(charter.name, info);
+            recordAgentSpawn(charter.name, mode);
+            if (this.eventBus) {
+                await this.eventBus.emit({
+                    type: 'session.created',
+                    sessionId: info.sessionId ?? undefined,
+                    agentName: charter.name,
+                    payload: { mode },
+                    timestamp: now,
+                });
+            }
+            return info;
+        }
+        catch (err) {
+            recordAgentError(charter.name, err instanceof Error ? err.constructor.name : 'unknown');
+            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();
+        }
+    }
+    /** Resume an existing agent session */
+    async resume(agentName) {
+        const span = tracer.startSpan('squad.agent.resume');
+        span.setAttribute('agent.name', agentName);
+        try {
+            const agent = this.agents.get(agentName);
+            if (!agent) {
+                throw new Error(`Agent '${agentName}' not found`);
+            }
+            agent.state = 'active';
+            agent.lastActiveAt = new Date();
+            return agent;
+        }
+        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();
+        }
+    }
+    /** Get info about a specific agent */
+    getAgent(name) {
+        return this.agents.get(name);
+    }
+    /** Get all agent session info */
+    getAllAgents() {
+        return Array.from(this.agents.values());
+    }
+    /** Destroy an agent session */
+    async destroy(agentName) {
+        const span = tracer.startSpan('squad.agent.destroy');
+        span.setAttribute('agent.name', agentName);
+        try {
+            const agent = this.agents.get(agentName);
+            if (!agent)
+                return;
+            if (this.eventBus) {
+                await this.eventBus.emit({
+                    type: 'session.destroyed',
+                    sessionId: agent.sessionId ?? undefined,
+                    agentName,
+                    payload: {},
+                    timestamp: new Date(),
+                });
+            }
+            const durationMs = agent.createdAt ? Date.now() - agent.createdAt.getTime() : 0;
+            recordAgentDuration(agentName, durationMs, 'success');
+            recordAgentDestroy(agentName);
+            agent.state = 'destroyed';
+            this.agents.delete(agentName);
+        }
+        catch (err) {
+            recordAgentError(agentName, err instanceof Error ? err.constructor.name : 'unknown');
+            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();
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

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

package/dist/agents/lifecycle.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 { SquadClientWithPool } from '../client/index.js';
+import { type TaskType } from './model-selector.js';
+/**
+ * Agent handle status.
+ */
+export type AgentStatus = 'spawning' | 'active' | 'idle' | 'error' | 'destroyed';
+/**
+ * Handle to a spawned agent session.
+ * Provides control and communication interface to the agent.
+ */
+export interface AgentHandle {
+    /** Agent name (e.g., 'verbal', 'fenster') */
+    agentName: string;
+    /** Underlying session ID from Squad Client */
+    sessionId: string;
+    /** Model being used for this agent */
+    model: string;
+    /** Current agent status */
+    status: AgentStatus;
+    /** Timestamp when agent was spawned */
+    createdAt: Date;
+    /** Last activity timestamp (for idle timeout) */
+    lastActivityAt: Date;
+    /**
+     * Send a message to the agent.
+     * @param prompt - User message or task prompt
+     */
+    sendMessage(prompt: string): Promise<void>;
+    /**
+     * Destroy the agent session gracefully.
+     * Saves history and cleans up resources.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Options for spawning an agent.
+ */
+export interface SpawnAgentOptions {
+    /** Agent name (e.g., 'verbal', 'fenster') */
+    agentName: string;
+    /** Task prompt to send to the agent */
+    task: string;
+    /** Task type for model selection */
+    taskType?: TaskType;
+    /** User-specified model override */
+    modelOverride?: string;
+    /** Team context content (team.md) */
+    teamContext?: string;
+    /** Routing rules content */
+    routingRules?: string;
+    /** Relevant decision records */
+    decisions?: string;
+    /** Idle timeout in milliseconds (default: 5 minutes) */
+    idleTimeout?: number;
+}
+/**
+ * Configuration for the lifecycle manager.
+ */
+export interface LifecycleManagerConfig {
+    /** Squad client instance */
+    client: SquadClientWithPool;
+    /** Path to team root directory */
+    teamRoot: string;
+    /** Default idle timeout (default: 5 minutes) */
+    defaultIdleTimeout?: number;
+}
+/**
+ * Manages the full lifecycle of agent sessions.
+ *
+ * Coordinates charter compilation, model selection, session creation,
+ * and graceful shutdown with history persistence.
+ */
+export declare class AgentLifecycleManager {
+    private client;
+    private teamRoot;
+    private defaultIdleTimeout;
+    private agents;
+    private idleCheckTimer;
+    constructor(config: LifecycleManagerConfig);
+    /**
+     * 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
+     */
+    spawnAgent(options: SpawnAgentOptions): Promise<AgentHandle>;
+    /**
+     * Destroy an agent gracefully.
+     * Saves history and cleans up session.
+     *
+     * @param handle - Agent handle to destroy
+     */
+    destroyAgent(handle: AgentHandle): Promise<void>;
+    /**
+     * List all active agent sessions.
+     *
+     * @returns Array of active agent handles
+     */
+    listActive(): AgentHandle[];
+    /**
+     * Get agent handle by session ID.
+     *
+     * @param sessionId - Session ID to look up
+     * @returns Agent handle or undefined
+     */
+    getAgent(sessionId: string): AgentHandle | undefined;
+    /**
+     * Shutdown all agents gracefully.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Start periodic idle timeout checker.
+     * @private
+     */
+    private startIdleChecker;
+    /**
+     * Extract model preference from charter content.
+     * @private
+     */
+    private extractModelPreference;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/agents/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,EAA6C,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAS/F;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;AAEjF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;IAChB,iDAAiD;IACjD,cAAc,EAAE,IAAI,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAE5B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAEjB,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,cAAc,CAA+B;gBAEzC,MAAM,EAAE,sBAAsB;IAS1C;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAyGlE;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBtD;;;;OAIG;IACH,UAAU,IAAI,WAAW,EAAE;IAM3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIpD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB/B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;CAI/B"}