@cleocode/core 2026.3.42 → 2026.3.44

package/dist/adrs/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ADR Core Types (ADR-017)
+ *
+ * Type definitions for parsed ADR frontmatter and operations.
+ *
+ * @task T4792
+ */
+/** Parsed ADR frontmatter from .md file */
+export interface AdrFrontmatter {
+    Date: string;
+    Status: 'proposed' | 'accepted' | 'superseded' | 'deprecated';
+    Accepted?: string;
+    Supersedes?: string;
+    'Superseded By'?: string;
+    Amends?: string;
+    'Amended By'?: string;
+    'Related ADRs'?: string;
+    'Related Tasks'?: string;
+    Gate?: 'HITL' | 'automated';
+    'Gate Status'?: 'pending' | 'passed' | 'waived';
+    Summary?: string;
+    Keywords?: string;
+    Topics?: string;
+}
+export interface AdrRecord {
+    id: string;
+    file: string;
+    title: string;
+    frontmatter: AdrFrontmatter;
+}
+export interface AdrSyncResult {
+    inserted: number;
+    updated: number;
+    skipped: number;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+export interface AdrListResult {
+    adrs: Array<{
+        id: string;
+        title: string;
+        status: string;
+        date: string;
+        filePath: string;
+    }>;
+    total: number;
+    filtered: number;
+}
+export interface AdrFindResult {
+    adrs: Array<{
+        id: string;
+        title: string;
+        status: string;
+        date: string;
+        filePath: string;
+        summary?: string;
+        keywords?: string;
+        topics?: string;
+        score: number;
+        matchedFields: string[];
+    }>;
+    query: string;
+    total: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adrs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adrs/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEhD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/adrs/validate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ADR Frontmatter Validation (ADR-017)
+ *
+ * Validates all ADR markdown files against schemas/adr-frontmatter.schema.json.
+ *
+ * @task T4792
+ */
+export interface ValidationError {
+    file: string;
+    field: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    checked: number;
+}
+/** @alias ValidationError — canonical name per ADR-017 spec */
+export type AdrValidationError = ValidationError;
+/** @alias ValidationResult — canonical name per ADR-017 spec */
+export type AdrValidationResult = ValidationResult;
+/** Validate all ADRs in .cleo/adrs/ against the schema */
+export declare function validateAllAdrs(projectRoot: string): Promise<ValidationResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/adrs/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/adrs/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEnD,0DAA0D;AAC1D,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+CpF"}

package/dist/agents/agent-schema.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Drizzle ORM schema for the CLEO Agent dimension.
+ *
+ * Defines the `agent_instances` table that tracks live agent processes,
+ * their health (heartbeat protocol), capacity, and error history.
+ *
+ * This is the DB-backed runtime registry -- distinct from the file-based
+ * skill agent registry in `skills/agents/registry.ts` which tracks
+ * installed agent *definitions*. This table tracks running agent *instances*.
+ *
+ * @module agents/agent-schema
+ */
+/** Agent instance status values matching DB CHECK constraint. */
+export declare const AGENT_INSTANCE_STATUSES: readonly ["starting", "active", "idle", "error", "crashed", "stopped"];
+/** Agent type values for classification. */
+export declare const AGENT_TYPES: readonly ["orchestrator", "executor", "researcher", "architect", "validator", "documentor", "custom"];
+export declare const agentInstances: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "agent_instances";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        agentType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string enum";
+            data: "orchestrator" | "executor" | "researcher" | "architect" | "validator" | "documentor" | "custom";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["orchestrator", "executor", "researcher", "architect", "validator", "documentor", "custom"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string enum";
+            data: "error" | "starting" | "active" | "idle" | "crashed" | "stopped";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["starting", "active", "idle", "error", "crashed", "stopped"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        sessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        taskId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        startedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        lastHeartbeat: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        stoppedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        errorCount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        totalTasksCompleted: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        capacity: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        metadataJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        parentAgentId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_instances";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
+export declare const agentErrorLog: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "agent_error_log";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        agentId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        errorType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "string enum";
+            data: "retriable" | "permanent" | "unknown";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["retriable", "permanent", "unknown"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        message: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        stack: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        occurredAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        resolved: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "agent_error_log";
+            dataType: "boolean";
+            data: boolean;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
+export type AgentInstanceRow = typeof agentInstances.$inferSelect;
+export type NewAgentInstanceRow = typeof agentInstances.$inferInsert;
+export type AgentErrorLogRow = typeof agentErrorLog.$inferSelect;
+export type NewAgentErrorLogRow = typeof agentErrorLog.$inferInsert;
+export type AgentInstanceStatus = (typeof AGENT_INSTANCE_STATUSES)[number];
+export type AgentType = (typeof AGENT_TYPES)[number];
+export type AgentErrorType = 'retriable' | 'permanent' | 'unknown';
+//# sourceMappingURL=agent-schema.d.ts.map

package/dist/agents/agent-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-schema.d.ts","sourceRoot":"","sources":["../../src/agents/agent-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,wEAO1B,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,WAAW,uGAQd,CAAC;AAMX,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyB1B,CAAC;AAMF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBzB,CAAC;AAMF,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAClE,MAAM,MAAM,mBAAmB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AACrE,MAAM,MAAM,gBAAgB,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AACjE,MAAM,MAAM,mBAAmB,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC"}

package/dist/agents/capacity.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Capacity tracking and load balancing for the Agent dimension.
+ *
+ * Tracks per-agent capacity (0.0-1.0) and provides queries for
+ * capacity-aware work distribution.
+ *
+ * @module agents/capacity
+ */
+import { type AgentInstanceRow, type AgentType } from './agent-schema.js';
+/**
+ * Update the capacity value for an agent instance.
+ *
+ * @param id - Agent instance ID
+ * @param capacity - New capacity value (0.0 to 1.0)
+ * @param cwd - Working directory
+ * @returns Updated agent row, or null if not found
+ */
+export declare function updateCapacity(id: string, capacity: number, cwd?: string): Promise<AgentInstanceRow | null>;
+/**
+ * Get the total available capacity across all active agents.
+ *
+ * Only considers agents in 'active' or 'idle' status.
+ * Returns the sum of all capacity values.
+ */
+export declare function getAvailableCapacity(cwd?: string): Promise<number>;
+/**
+ * Find the agent with the most available capacity.
+ *
+ * @param agentType - Optional type filter
+ * @param cwd - Working directory
+ * @returns Agent with highest capacity, or null if no active agents
+ */
+export declare function findLeastLoadedAgent(agentType?: AgentType, cwd?: string): Promise<AgentInstanceRow | null>;
+/**
+ * Check if the system is overloaded (total capacity below threshold).
+ *
+ * @param threshold - Minimum acceptable capacity (default: 0.1)
+ * @param cwd - Working directory
+ * @returns true if total available capacity is below the threshold
+ */
+export declare function isOverloaded(threshold?: number, cwd?: string): Promise<boolean>;
+/** Capacity summary for reporting. */
+export interface CapacitySummary {
+    totalCapacity: number;
+    activeAgentCount: number;
+    averageCapacity: number;
+    overloaded: boolean;
+    threshold: number;
+}
+/**
+ * Get a capacity summary across the entire agent pool.
+ *
+ * @param threshold - Overload threshold (default: 0.1)
+ * @param cwd - Working directory
+ */
+export declare function getCapacitySummary(threshold?: number, cwd?: string): Promise<CapacitySummary>;
+//# sourceMappingURL=capacity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capacity.d.ts","sourceRoot":"","sources":["../../src/agents/capacity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAkB,MAAM,mBAAmB,CAAC;AAO1F;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAclC;AAMD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxE;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,CAAC,EAAE,SAAS,EACrB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAqBlC;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,SAAS,GAAE,MAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,GAAE,MAAY,EACvB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC,CAY1B"}

package/dist/agents/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent dimension -- runtime tracking, health monitoring, self-healing, and capacity.
+ *
+ * This module provides the complete Agent dimension for the BRAIN specification:
+ *
+ * - **Registry**: CRUD for agent instances (register, deregister, heartbeat, queries)
+ * - **Health**: Crash detection via heartbeat protocol, health reports
+ * - **Self-Healing**: Retry with exponential backoff, crashed agent recovery
+ * - **Capacity**: Load awareness, least-loaded agent selection, overload detection
+ *
+ * @module agents
+ */
+export { AGENT_INSTANCE_STATUSES, AGENT_TYPES, type AgentErrorLogRow, type AgentErrorType, type AgentInstanceRow, type AgentInstanceStatus, type AgentType, agentErrorLog, agentInstances, type NewAgentErrorLogRow, type NewAgentInstanceRow, } from './agent-schema.js';
+export { type CapacitySummary, findLeastLoadedAgent, getAvailableCapacity, getCapacitySummary, isOverloaded, updateCapacity, } from './capacity.js';
+export { type AgentHealthReport, checkAgentHealth, classifyError, deregisterAgent, generateAgentId, getAgentErrorHistory, getAgentInstance, getHealthReport, heartbeat, incrementTasksCompleted, type ListAgentFilters, listAgentInstances, markCrashed, type RegisterAgentOptions, registerAgent, type UpdateStatusOptions, updateAgentStatus, } from './registry.js';
+export { type AgentRecoveryResult, calculateDelay, createRetryPolicy, DEFAULT_RETRY_POLICY, type RetryPolicy, type RetryResult, recoverCrashedAgents, shouldRetry, withRetry, } from './retry.js';
+//# 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":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,aAAa,EACb,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,eAAe,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,WAAW,EACX,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,mBAAmB,EACxB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,mBAAmB,EACxB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/agents/registry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent instance registry -- runtime tracking of live agent processes.
+ *
+ * Provides CRUD operations for the `agent_instances` table:
+ * registration, deregistration, heartbeat, status updates, and queries.
+ *
+ * This is the DB-backed runtime registry for live agent *instances*.
+ * The file-based registry in `skills/agents/registry.ts` tracks installed
+ * agent *definitions* -- those are complementary, not competing, concepts.
+ *
+ * @module agents/registry
+ */
+import { type AgentErrorLogRow, type AgentErrorType, type AgentInstanceRow, type AgentInstanceStatus, type AgentType } from './agent-schema.js';
+/**
+ * Generate a unique agent instance ID.
+ * Format: `agt_{YYYYMMDDHHmmss}_{6hex}`
+ */
+export declare function generateAgentId(): string;
+/** Options for registering a new agent instance. */
+export interface RegisterAgentOptions {
+    agentType: AgentType;
+    sessionId?: string;
+    taskId?: string;
+    parentAgentId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Register a new agent instance in the database.
+ * Sets initial status to 'starting' and records the first heartbeat.
+ */
+export declare function registerAgent(opts: RegisterAgentOptions, cwd?: string): Promise<AgentInstanceRow>;
+/**
+ * Deregister (stop) an agent instance.
+ * Sets status to 'stopped' and records the stop timestamp.
+ */
+export declare function deregisterAgent(id: string, cwd?: string): Promise<AgentInstanceRow | null>;
+/**
+ * Record a heartbeat for an agent instance.
+ * Updates `last_heartbeat` and returns the current status so the agent
+ * can detect if it has been externally marked for shutdown.
+ */
+export declare function heartbeat(id: string, cwd?: string): Promise<AgentInstanceStatus | null>;
+/** Options for updating agent status. */
+export interface UpdateStatusOptions {
+    status: AgentInstanceStatus;
+    error?: string;
+    taskId?: string;
+}
+/**
+ * Update agent status with optional error tracking.
+ * When status is 'error' or 'crashed', increments the error count
+ * and logs the error to the agent_error_log table.
+ */
+export declare function updateAgentStatus(id: string, opts: UpdateStatusOptions, cwd?: string): Promise<AgentInstanceRow | null>;
+/**
+ * Increment the completed task count for an agent.
+ */
+export declare function incrementTasksCompleted(id: string, cwd?: string): Promise<void>;
+/** Filters for listing agent instances. */
+export interface ListAgentFilters {
+    status?: AgentInstanceStatus | AgentInstanceStatus[];
+    agentType?: AgentType | AgentType[];
+    sessionId?: string;
+    parentAgentId?: string;
+}
+/**
+ * List agent instances with optional filters.
+ */
+export declare function listAgentInstances(filters?: ListAgentFilters, cwd?: string): Promise<AgentInstanceRow[]>;
+/**
+ * Get a single agent instance by ID.
+ */
+export declare function getAgentInstance(id: string, cwd?: string): Promise<AgentInstanceRow | null>;
+/**
+ * Classify an error as retriable, permanent, or unknown.
+ *
+ * Retriable errors are transient conditions (network, rate limits, locks)
+ * where a retry may succeed. Permanent errors are structural (auth,
+ * not found, constraint violations) where retrying is pointless.
+ */
+export declare function classifyError(error: unknown): AgentErrorType;
+/**
+ * Get the error history for a specific agent.
+ */
+export declare function getAgentErrorHistory(agentId: string, cwd?: string): Promise<AgentErrorLogRow[]>;
+/**
+ * Check agent health by finding instances whose last heartbeat exceeds the threshold.
+ * Default threshold: 30000ms (30 seconds) as specified by the BRAIN spec.
+ *
+ * Returns agents that appear to have crashed (stale heartbeat).
+ */
+export declare function checkAgentHealth(thresholdMs?: number, cwd?: string): Promise<AgentInstanceRow[]>;
+/**
+ * Mark an agent instance as crashed.
+ * Increments error count and sets status to 'crashed'.
+ */
+export declare function markCrashed(id: string, reason?: string, cwd?: string): Promise<AgentInstanceRow | null>;
+/** Agent health report summary. */
+export interface AgentHealthReport {
+    total: number;
+    active: number;
+    idle: number;
+    starting: number;
+    error: number;
+    crashed: number;
+    stopped: number;
+    totalErrors: number;
+    staleAgents: AgentInstanceRow[];
+}
+/**
+ * Generate a health report summarizing all agent instances.
+ * Includes counts by status and identifies stale agents.
+ */
+export declare function getHealthReport(thresholdMs?: number, cwd?: string): Promise<AgentHealthReport>;
+//# sourceMappingURL=registry.d.ts.map

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

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