@bradygaster/squad-sdk 0.6.2 → 0.8.0

package/dist/ralph/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ralph — Work Monitor (PRD 8)
+ *
+ * Persistent SDK session that monitors agent work in real time.
+ * Replaces ephemeral polling spawns with an event-driven observer
+ * that accumulates knowledge across monitoring cycles.
+ *
+ * Three monitoring layers:
+ *   1. In-session: Event subscriptions via EventBus
+ *   2. Watchdog: Periodic health checks on session pool
+ *   3. Cloud heartbeat: External health signal (future)
+ */
+import type { EventBus } from '../client/event-bus.js';
+export interface MonitorConfig {
+    /** Team root directory */
+    teamRoot: string;
+    /** Health check interval (ms, default: 30000) */
+    healthCheckInterval?: number;
+    /** Stale session threshold (ms, default: 300000) */
+    staleSessionThreshold?: number;
+    /** Path to persist monitor state for crash recovery */
+    statePath?: string;
+}
+export interface AgentWorkStatus {
+    agentName: string;
+    sessionId: string;
+    status: 'working' | 'idle' | 'stale' | 'error';
+    lastActivity: Date;
+    currentTask?: string;
+    milestones: string[];
+}
+export interface MonitorState {
+    /** Timestamp of last health check */
+    lastHealthCheck: Date | null;
+    /** Per-agent work status */
+    agents: Map<string, AgentWorkStatus>;
+    /** Accumulated observations across cycles */
+    observations: string[];
+}
+export declare class RalphMonitor {
+    private config;
+    private state;
+    private eventBus;
+    constructor(config: MonitorConfig);
+    /** Start monitoring — subscribe to EventBus and begin health checks */
+    start(eventBus: EventBus): Promise<void>;
+    /** Handle an incoming event from the EventBus */
+    private handleEvent;
+    /** Run a health check across all tracked agent sessions */
+    healthCheck(): Promise<AgentWorkStatus[]>;
+    /** Get current work status for all agents */
+    getStatus(): AgentWorkStatus[];
+    /** Stop monitoring and persist final state */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,wBAAwB,CAAC;AAInE,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IAEjB,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,oDAAoD;IACpD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC/C,YAAY,EAAE,IAAI,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,4BAA4B;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrC,6CAA6C;IAC7C,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,QAAQ,CAAyB;gBAE7B,MAAM,EAAE,aAAa;IAWjC,uEAAuE;IACjE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C,iDAAiD;IACjD,OAAO,CAAC,WAAW;IAMnB,2DAA2D;IACrD,WAAW,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAQ/C,6CAA6C;IAC7C,SAAS,IAAI,eAAe,EAAE;IAI9B,8CAA8C;IACxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/ralph/index.js

@@ -0,0 +1,61 @@
+/**
+ * Ralph — Work Monitor (PRD 8)
+ *
+ * Persistent SDK session that monitors agent work in real time.
+ * Replaces ephemeral polling spawns with an event-driven observer
+ * that accumulates knowledge across monitoring cycles.
+ *
+ * Three monitoring layers:
+ *   1. In-session: Event subscriptions via EventBus
+ *   2. Watchdog: Periodic health checks on session pool
+ *   3. Cloud heartbeat: External health signal (future)
+ */
+// --- Ralph Monitor ---
+export class RalphMonitor {
+    config;
+    state;
+    eventBus = null;
+    constructor(config) {
+        this.config = config;
+        this.state = {
+            lastHealthCheck: null,
+            agents: new Map(),
+            observations: [],
+        };
+        // TODO: PRD 8 — Load persisted state from statePath if exists
+        // TODO: PRD 8 — Initialize as persistent SDK session via resumeSession('squad-ralph')
+    }
+    /** Start monitoring — subscribe to EventBus and begin health checks */
+    async start(eventBus) {
+        this.eventBus = eventBus;
+        // TODO: PRD 8 — Subscribe to session lifecycle events
+        // TODO: PRD 8 — Subscribe to agent.milestone events
+        // TODO: PRD 8 — Start periodic health check timer
+        // TODO: PRD 8 — Register onSessionStart hook to track new agents
+    }
+    /** Handle an incoming event from the EventBus */
+    handleEvent(event) {
+        // TODO: PRD 8 — Update agent work status based on event type
+        // TODO: PRD 8 — Extract [MILESTONE] markers from agent output
+        // TODO: PRD 8 — Detect stale sessions and flag for coordinator
+    }
+    /** Run a health check across all tracked agent sessions */
+    async healthCheck() {
+        // TODO: PRD 8 — Check each session's last activity timestamp
+        // TODO: PRD 8 — Mark stale sessions (no activity > threshold)
+        // TODO: PRD 8 — Persist state to statePath for crash recovery
+        this.state.lastHealthCheck = new Date();
+        return Array.from(this.state.agents.values());
+    }
+    /** Get current work status for all agents */
+    getStatus() {
+        return Array.from(this.state.agents.values());
+    }
+    /** Stop monitoring and persist final state */
+    async stop() {
+        // TODO: PRD 8 — Unsubscribe from EventBus
+        // TODO: PRD 8 — Stop health check timer
+        // TODO: PRD 8 — Persist final state to statePath
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/ralph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ralph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAsCH,wBAAwB;AAExB,MAAM,OAAO,YAAY;IACf,MAAM,CAAgB;IACtB,KAAK,CAAe;IACpB,QAAQ,GAAoB,IAAI,CAAC;IAEzC,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG;YACX,eAAe,EAAE,IAAI;YACrB,MAAM,EAAE,IAAI,GAAG,EAAE;YACjB,YAAY,EAAE,EAAE;SACjB,CAAC;QACF,8DAA8D;QAC9D,sFAAsF;IACxF,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,KAAK,CAAC,QAAkB;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,sDAAsD;QACtD,oDAAoD;QACpD,kDAAkD;QAClD,iEAAiE;IACnE,CAAC;IAED,iDAAiD;IACzC,WAAW,CAAC,KAAiB;QACnC,6DAA6D;QAC7D,8DAA8D;QAC9D,+DAA+D;IACjE,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,WAAW;QACf,6DAA6D;QAC7D,8DAA8D;QAC9D,8DAA8D;QAC9D,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,IAAI,IAAI,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,6CAA6C;IAC7C,SAAS;QACP,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,IAAI;QACR,0CAA0C;QAC1C,wCAAwC;QACxC,iDAAiD;IACnD,CAAC;CACF"}

package/dist/resolution.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Squad directory resolution — walk-up and global path algorithms.
+ *
+ * resolveSquad()            — find .squad/ by walking up from startDir to .git boundary
+ * resolveGlobalSquadPath()  — platform-specific global config directory
+ *
+ * @module resolution
+ */
+/**
+ * Walk up the directory tree from `startDir` looking for a `.squad/` directory.
+ *
+ * Stops at the repository root (the directory containing `.git`).
+ * Returns the **absolute path** to the `.squad/` directory, or `null` if none is found.
+ *
+ * Handles nested repos, worktrees (`.git` file pointing elsewhere), and symlinks.
+ *
+ * @param startDir - Directory to start searching from. Defaults to `process.cwd()`.
+ * @returns Absolute path to `.squad/` or `null`.
+ */
+export declare function resolveSquad(startDir?: string): string | null;
+/**
+ * Return the platform-specific global Squad configuration directory.
+ *
+ * | Platform | Path                                       |
+ * |----------|--------------------------------------------|
+ * | Windows  | `%APPDATA%/squad/`                         |
+ * | macOS    | `~/Library/Application Support/squad/`      |
+ * | Linux    | `$XDG_CONFIG_HOME/squad/` (default `~/.config/squad/`) |
+ *
+ * The directory is created (recursively) if it does not already exist.
+ *
+ * @returns Absolute path to the global squad config directory.
+ */
+export declare function resolveGlobalSquadPath(): string;
+/**
+ * Validate that a file path is within `.squad/` or the system temp directory.
+ *
+ * Use this guard before writing any scratch/temp/state files to ensure Squad
+ * never clutters the repo root or arbitrary filesystem locations.
+ *
+ * @param filePath  - Absolute path to validate.
+ * @param squadRoot - Absolute path to the `.squad/` directory (e.g. from `resolveSquad()`).
+ * @returns The resolved absolute `filePath` if it is safe.
+ * @throws If `filePath` is outside `.squad/` and not in the system temp directory.
+ */
+export declare function ensureSquadPath(filePath: string, squadRoot: string): string;
+//# sourceMappingURL=resolution.d.ts.map

package/dist/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","sourceRoot":"","sources":["../src/resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2B7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAuB/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmB3E"}

package/dist/resolution.js

@@ -0,0 +1,106 @@
+/**
+ * Squad directory resolution — walk-up and global path algorithms.
+ *
+ * resolveSquad()            — find .squad/ by walking up from startDir to .git boundary
+ * resolveGlobalSquadPath()  — platform-specific global config directory
+ *
+ * @module resolution
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+/**
+ * Walk up the directory tree from `startDir` looking for a `.squad/` directory.
+ *
+ * Stops at the repository root (the directory containing `.git`).
+ * Returns the **absolute path** to the `.squad/` directory, or `null` if none is found.
+ *
+ * Handles nested repos, worktrees (`.git` file pointing elsewhere), and symlinks.
+ *
+ * @param startDir - Directory to start searching from. Defaults to `process.cwd()`.
+ * @returns Absolute path to `.squad/` or `null`.
+ */
+export function resolveSquad(startDir) {
+    let current = path.resolve(startDir ?? process.cwd());
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const candidate = path.join(current, '.squad');
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        // Stop if we hit a .git boundary (directory or worktree file)
+        const gitMarker = path.join(current, '.git');
+        if (fs.existsSync(gitMarker)) {
+            // We've reached the repo root — don't walk higher
+            return null;
+        }
+        const parent = path.dirname(current);
+        // Filesystem root reached — nowhere left to walk
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+/**
+ * Return the platform-specific global Squad configuration directory.
+ *
+ * | Platform | Path                                       |
+ * |----------|--------------------------------------------|
+ * | Windows  | `%APPDATA%/squad/`                         |
+ * | macOS    | `~/Library/Application Support/squad/`      |
+ * | Linux    | `$XDG_CONFIG_HOME/squad/` (default `~/.config/squad/`) |
+ *
+ * The directory is created (recursively) if it does not already exist.
+ *
+ * @returns Absolute path to the global squad config directory.
+ */
+export function resolveGlobalSquadPath() {
+    const platform = process.platform;
+    let base;
+    if (platform === 'win32') {
+        // %APPDATA% is always set on Windows; fall back to %LOCALAPPDATA%, then homedir
+        base = process.env['APPDATA']
+            ?? process.env['LOCALAPPDATA']
+            ?? path.join(os.homedir(), 'AppData', 'Roaming');
+    }
+    else if (platform === 'darwin') {
+        base = path.join(os.homedir(), 'Library', 'Application Support');
+    }
+    else {
+        // Linux / other POSIX — respect XDG_CONFIG_HOME
+        base = process.env['XDG_CONFIG_HOME'] ?? path.join(os.homedir(), '.config');
+    }
+    const globalDir = path.join(base, 'squad');
+    if (!fs.existsSync(globalDir)) {
+        fs.mkdirSync(globalDir, { recursive: true });
+    }
+    return globalDir;
+}
+/**
+ * Validate that a file path is within `.squad/` or the system temp directory.
+ *
+ * Use this guard before writing any scratch/temp/state files to ensure Squad
+ * never clutters the repo root or arbitrary filesystem locations.
+ *
+ * @param filePath  - Absolute path to validate.
+ * @param squadRoot - Absolute path to the `.squad/` directory (e.g. from `resolveSquad()`).
+ * @returns The resolved absolute `filePath` if it is safe.
+ * @throws If `filePath` is outside `.squad/` and not in the system temp directory.
+ */
+export function ensureSquadPath(filePath, squadRoot) {
+    const resolved = path.resolve(filePath);
+    const resolvedSquad = path.resolve(squadRoot);
+    const resolvedTmp = path.resolve(os.tmpdir());
+    // Allow paths inside the .squad/ directory
+    if (resolved === resolvedSquad || resolved.startsWith(resolvedSquad + path.sep)) {
+        return resolved;
+    }
+    // Allow paths inside the system temp directory
+    if (resolved === resolvedTmp || resolved.startsWith(resolvedTmp + path.sep)) {
+        return resolved;
+    }
+    throw new Error(`Path "${resolved}" is outside the .squad/ directory ("${resolvedSquad}"). ` +
+        'All squad scratch/temp/state files must be written inside .squad/ or the system temp directory.');
+}
+//# sourceMappingURL=resolution.js.map

package/dist/resolution.js.map

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

package/dist/runtime/benchmarks.d.ts

@@ -0,0 +1,121 @@
+/**
+ * M6-11: Performance profiling & benchmarks
+ * Provides benchmark utilities to measure Squad operation timings.
+ *
+ * @module runtime/benchmarks
+ */
+/**
+ * Result of a single benchmark run.
+ */
+export interface BenchmarkResult {
+    /** Benchmark name */
+    name: string;
+    /** Number of iterations run */
+    iterations: number;
+    /** Average time in ms */
+    avg: number;
+    /** Minimum time in ms */
+    min: number;
+    /** Maximum time in ms */
+    max: number;
+    /** 95th percentile time in ms */
+    p95: number;
+    /** 99th percentile time in ms */
+    p99: number;
+}
+/**
+ * Timing summary returned by individual benchmark functions.
+ */
+export interface TimingResult {
+    avg: number;
+    min: number;
+    max: number;
+    p95: number;
+}
+/**
+ * Full benchmark report returned by `runAll`.
+ */
+export interface BenchmarkReport {
+    results: BenchmarkResult[];
+    totalTime: number;
+    timestamp: string;
+}
+/**
+ * An async operation that can be benchmarked.
+ */
+export type BenchmarkFn = () => Promise<void> | void;
+/**
+ * Calculate percentile from a sorted array of numbers.
+ */
+export declare function percentile(sorted: number[], p: number): number;
+/**
+ * Measure the execution time of a function over N iterations and return stats.
+ */
+export declare function measureIterations(fn: BenchmarkFn, iterations: number): Promise<{
+    avg: number;
+    min: number;
+    max: number;
+    p95: number;
+    p99: number;
+    timings: number[];
+}>;
+/**
+ * Runs performance benchmarks on Squad operations.
+ *
+ * Usage:
+ * ```ts
+ * const suite = new BenchmarkSuite();
+ * const report = await suite.runAll(100);
+ * console.log(formatBenchmarkReport(report.results));
+ * ```
+ */
+export declare class BenchmarkSuite {
+    private benchmarks;
+    constructor();
+    /**
+     * Register a custom benchmark.
+     */
+    register(name: string, fn: BenchmarkFn): void;
+    /**
+     * Unregister a benchmark by name.
+     */
+    unregister(name: string): boolean;
+    /**
+     * List all registered benchmark names.
+     */
+    list(): string[];
+    /**
+     * Benchmark config loading.
+     */
+    benchmarkConfigLoad(iterations: number): Promise<TimingResult>;
+    /**
+     * Benchmark charter compilation.
+     */
+    benchmarkCharterCompile(iterations: number): Promise<TimingResult>;
+    /**
+     * Benchmark routing operations.
+     */
+    benchmarkRouting(iterations: number): Promise<TimingResult>;
+    /**
+     * Benchmark model selection.
+     */
+    benchmarkModelSelection(iterations: number): Promise<TimingResult>;
+    /**
+     * Benchmark export/import round-trip.
+     */
+    benchmarkExportImport(iterations: number): Promise<TimingResult>;
+    /**
+     * Run all registered benchmarks and produce a full report.
+     */
+    runAll(iterations?: number): Promise<BenchmarkReport>;
+    private configLoadOp;
+    private charterCompileOp;
+    private routingOp;
+    private modelSelectionOp;
+    private exportImportOp;
+}
+/**
+ * Format benchmark results as a terminal-formatted table.
+ */
+export declare function formatBenchmarkReport(results: BenchmarkResult[]): string;
+//# sourceMappingURL=benchmarks.d.ts.map

package/dist/runtime/benchmarks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmarks.d.ts","sourceRoot":"","sources":["../../src/runtime/benchmarks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAMrD;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,WAAW,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAyBjG;AAMD;;;;;;;;;GASG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,UAAU,CAAuC;;IAWzD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAI7C;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;OAEG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKpE;;OAEG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKxE;;OAEG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKjE;;OAEG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKxE;;OAEG;IACG,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKtE;;OAEG;IACG,MAAM,CAAC,UAAU,GAAE,MAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IA4BhE,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,cAAc;CAYvB;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAiCxE"}

package/dist/runtime/benchmarks.js

@@ -0,0 +1,251 @@
+/**
+ * M6-11: Performance profiling & benchmarks
+ * Provides benchmark utilities to measure Squad operation timings.
+ *
+ * @module runtime/benchmarks
+ */
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Calculate percentile from a sorted array of numbers.
+ */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+/**
+ * Measure the execution time of a function over N iterations and return stats.
+ */
+export async function measureIterations(fn, iterations) {
+    if (iterations < 1) {
+        throw new Error('Iterations must be at least 1');
+    }
+    const timings = [];
+    for (let i = 0; i < iterations; i++) {
+        const start = performance.now();
+        await fn();
+        const end = performance.now();
+        timings.push(end - start);
+    }
+    timings.sort((a, b) => a - b);
+    const sum = timings.reduce((a, b) => a + b, 0);
+    return {
+        avg: sum / timings.length,
+        min: timings[0],
+        max: timings[timings.length - 1],
+        p95: percentile(timings, 95),
+        p99: percentile(timings, 99),
+        timings,
+    };
+}
+// ============================================================================
+// BenchmarkSuite
+// ============================================================================
+/**
+ * Runs performance benchmarks on Squad operations.
+ *
+ * Usage:
+ * ```ts
+ * const suite = new BenchmarkSuite();
+ * const report = await suite.runAll(100);
+ * console.log(formatBenchmarkReport(report.results));
+ * ```
+ */
+export class BenchmarkSuite {
+    benchmarks = new Map();
+    constructor() {
+        // Register built-in benchmarks
+        this.benchmarks.set('configLoad', () => this.configLoadOp());
+        this.benchmarks.set('charterCompile', () => this.charterCompileOp());
+        this.benchmarks.set('routing', () => this.routingOp());
+        this.benchmarks.set('modelSelection', () => this.modelSelectionOp());
+        this.benchmarks.set('exportImport', () => this.exportImportOp());
+    }
+    /**
+     * Register a custom benchmark.
+     */
+    register(name, fn) {
+        this.benchmarks.set(name, fn);
+    }
+    /**
+     * Unregister a benchmark by name.
+     */
+    unregister(name) {
+        return this.benchmarks.delete(name);
+    }
+    /**
+     * List all registered benchmark names.
+     */
+    list() {
+        return [...this.benchmarks.keys()];
+    }
+    /**
+     * Benchmark config loading.
+     */
+    async benchmarkConfigLoad(iterations) {
+        const stats = await measureIterations(() => this.configLoadOp(), iterations);
+        return { avg: stats.avg, min: stats.min, max: stats.max, p95: stats.p95 };
+    }
+    /**
+     * Benchmark charter compilation.
+     */
+    async benchmarkCharterCompile(iterations) {
+        const stats = await measureIterations(() => this.charterCompileOp(), iterations);
+        return { avg: stats.avg, min: stats.min, max: stats.max, p95: stats.p95 };
+    }
+    /**
+     * Benchmark routing operations.
+     */
+    async benchmarkRouting(iterations) {
+        const stats = await measureIterations(() => this.routingOp(), iterations);
+        return { avg: stats.avg, min: stats.min, max: stats.max, p95: stats.p95 };
+    }
+    /**
+     * Benchmark model selection.
+     */
+    async benchmarkModelSelection(iterations) {
+        const stats = await measureIterations(() => this.modelSelectionOp(), iterations);
+        return { avg: stats.avg, min: stats.min, max: stats.max, p95: stats.p95 };
+    }
+    /**
+     * Benchmark export/import round-trip.
+     */
+    async benchmarkExportImport(iterations) {
+        const stats = await measureIterations(() => this.exportImportOp(), iterations);
+        return { avg: stats.avg, min: stats.min, max: stats.max, p95: stats.p95 };
+    }
+    /**
+     * Run all registered benchmarks and produce a full report.
+     */
+    async runAll(iterations = 100) {
+        const totalStart = performance.now();
+        const results = [];
+        for (const [name, fn] of this.benchmarks) {
+            const stats = await measureIterations(fn, iterations);
+            results.push({
+                name,
+                iterations,
+                avg: stats.avg,
+                min: stats.min,
+                max: stats.max,
+                p95: stats.p95,
+                p99: stats.p99,
+            });
+        }
+        const totalTime = performance.now() - totalStart;
+        return {
+            results,
+            totalTime,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // -- Internal operations simulating real Squad work --
+    configLoadOp() {
+        // Simulate config parsing: build and validate a config-like object
+        const config = {
+            version: '1.0.0',
+            models: { defaultModel: 'claude-sonnet-4.5', defaultTier: 'standard', fallbackChains: { premium: [], standard: [], fast: [] } },
+            routing: { rules: [{ workType: 'feature-dev', agents: ['@coordinator'] }] },
+        };
+        JSON.parse(JSON.stringify(config));
+    }
+    charterCompileOp() {
+        // Simulate agent charter compilation from markdown
+        const charter = `# Agent Charter\n\n## Role\nCore developer\n\n## Skills\n- TypeScript\n- Testing\n\n## Rules\n1. Follow conventions\n2. Write tests`;
+        const lines = charter.split('\n');
+        const sections = {};
+        let current = '';
+        for (const line of lines) {
+            if (line.startsWith('## ')) {
+                current = line.slice(3).trim().toLowerCase();
+                sections[current] = [];
+            }
+            else if (current) {
+                sections[current].push(line);
+            }
+        }
+        JSON.stringify(sections);
+    }
+    routingOp() {
+        // Simulate routing rule evaluation
+        const rules = [
+            { workType: 'feature-dev', agents: ['fenster'], patterns: [/feature/i, /feat/i] },
+            { workType: 'bug-fix', agents: ['kujan'], patterns: [/bug/i, /fix/i] },
+            { workType: 'testing', agents: ['verbal'], patterns: [/test/i, /spec/i] },
+            { workType: 'documentation', agents: ['mcmanus'], patterns: [/doc/i, /readme/i] },
+        ];
+        const input = 'Implement a new feature for the routing module';
+        for (const rule of rules) {
+            for (const pattern of rule.patterns) {
+                if (pattern.test(input))
+                    break;
+            }
+        }
+    }
+    modelSelectionOp() {
+        // Simulate model selection logic
+        const tiers = {
+            premium: ['claude-opus-4.6', 'gpt-5.2'],
+            standard: ['claude-sonnet-4.5', 'gpt-5.1-codex'],
+            fast: ['claude-haiku-4.5', 'gpt-5-mini'],
+        };
+        const role = 'developer';
+        const complexity = 7;
+        const tier = complexity > 8 ? 'premium' : complexity > 4 ? 'standard' : 'fast';
+        const models = tiers[tier];
+        const _selected = models[0];
+        void _selected;
+        void role;
+    }
+    exportImportOp() {
+        // Simulate export → serialize → deserialize → import round-trip
+        const bundle = {
+            config: { version: '1.0.0', models: {}, routing: { rules: [] } },
+            agents: [{ name: 'fenster', role: 'developer', content: '# Fenster' }],
+            skills: ['typescript', 'testing'],
+            routingRules: [{ pattern: 'feature/*', agent: 'fenster' }],
+            metadata: { version: '1.0.0', timestamp: new Date().toISOString(), source: 'test' },
+        };
+        const serialized = JSON.stringify(bundle);
+        JSON.parse(serialized);
+    }
+}
+// ============================================================================
+// Report Formatting
+// ============================================================================
+/**
+ * Format benchmark results as a terminal-formatted table.
+ */
+export function formatBenchmarkReport(results) {
+    if (results.length === 0) {
+        return 'No benchmark results to display.';
+    }
+    const COL_NAME = 24;
+    const COL_NUM = 12;
+    const header = [
+        'Name'.padEnd(COL_NAME),
+        'Iter'.padStart(COL_NUM),
+        'Avg (ms)'.padStart(COL_NUM),
+        'Min (ms)'.padStart(COL_NUM),
+        'Max (ms)'.padStart(COL_NUM),
+        'P95 (ms)'.padStart(COL_NUM),
+        'P99 (ms)'.padStart(COL_NUM),
+    ].join('  ');
+    const separator = '─'.repeat(header.length);
+    const rows = results.map((r) => {
+        return [
+            r.name.padEnd(COL_NAME),
+            String(r.iterations).padStart(COL_NUM),
+            r.avg.toFixed(3).padStart(COL_NUM),
+            r.min.toFixed(3).padStart(COL_NUM),
+            r.max.toFixed(3).padStart(COL_NUM),
+            r.p95.toFixed(3).padStart(COL_NUM),
+            r.p99.toFixed(3).padStart(COL_NUM),
+        ].join('  ');
+    });
+    return [separator, header, separator, ...rows, separator].join('\n');
+}
+//# sourceMappingURL=benchmarks.js.map