@framers/agentos 0.1.121 → 0.1.123

package/dist/emergent/ManageSkillsTool.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview ManageSkillsTool — ITool implementation that enables agents to
+ * dynamically enable, disable, and search for skills at runtime.
+ *
+ * @module @framers/agentos/emergent/ManageSkillsTool
+ *
+ * Agents call `manage_skills` to self-modify their active skill set. The tool
+ * enforces an allowlist-based permission model:
+ * - Wildcard (`'*'`) allows all skills unconditionally.
+ * - Exact skill ID matches are always permitted.
+ * - Category-based allowlist entries (`'category:X'`) permit any skill in that category.
+ * - Same-category expansion: if any skill in category X is already active, other
+ *   skills in X are also permitted without explicit allowlist entry.
+ * - New categories may require approval when `requireApprovalForNewCategories` is set.
+ *
+ * Locked skills cannot be disabled.
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../core/tools/ITool.js';
+/**
+ * Minimal skill descriptor used for active skill listing and search results.
+ */
+export interface SkillDescriptor {
+    /** Unique skill identifier. */
+    skillId: string;
+    /** Human-readable skill name. */
+    name: string;
+    /** Category the skill belongs to. */
+    category: string;
+}
+/**
+ * Extended skill descriptor returned by search, including a description.
+ */
+export interface SkillSearchResult extends SkillDescriptor {
+    /** Natural language description of the skill's purpose. */
+    description: string;
+}
+/**
+ * Input arguments accepted by the `manage_skills` tool.
+ * Discriminated on the `action` field.
+ */
+export interface ManageSkillsInput extends Record<string, any> {
+    /** The action to perform: enable, disable, search, or list. */
+    action: 'enable' | 'disable' | 'search' | 'list';
+    /** Skill ID to enable or disable (required for enable/disable). */
+    skillId?: string;
+    /** Search query string (required for search). */
+    query?: string;
+}
+/**
+ * Dependencies injected into the {@link ManageSkillsTool} constructor.
+ */
+export interface ManageSkillsDeps {
+    /** Configuration controlling allowlist and approval requirements. */
+    config: {
+        /**
+         * Allowlist of permitted skill IDs or patterns.
+         * - `['*']` → all skills allowed.
+         * - Exact skill IDs are matched literally.
+         * - `'category:X'` → any skill in category X is allowed.
+         */
+        allowlist: string[];
+        /** Whether enabling skills in new categories requires approval. */
+        requireApprovalForNewCategories: boolean;
+    };
+    /** Returns the currently active skills for the agent. */
+    getActiveSkills: () => SkillDescriptor[];
+    /** Returns the list of skill IDs that cannot be disabled. */
+    getLockedSkills: () => string[];
+    /** Load and activate a skill by its ID. Returns the skill descriptor. */
+    loadSkill: (id: string) => Promise<SkillDescriptor>;
+    /** Unload and deactivate a skill by its ID. */
+    unloadSkill: (id: string) => void;
+    /** Search for available skills matching a query string. */
+    searchSkills: (query: string) => SkillSearchResult[];
+}
+/**
+ * ITool implementation enabling agents to dynamically manage their skill set
+ * at runtime, subject to allowlist and lock constraints.
+ *
+ * @example
+ * ```ts
+ * const tool = new ManageSkillsTool({
+ *   config: { allowlist: ['*'], requireApprovalForNewCategories: false },
+ *   getActiveSkills: () => agent.skills,
+ *   getLockedSkills: () => ['core-reasoning'],
+ *   loadSkill: (id) => skillRegistry.load(id),
+ *   unloadSkill: (id) => skillRegistry.unload(id),
+ *   searchSkills: (q) => skillRegistry.search(q),
+ * });
+ * ```
+ */
+export declare class ManageSkillsTool implements ITool<ManageSkillsInput> {
+    /** @inheritdoc */
+    readonly id = "com.framers.emergent.manage-skills";
+    /** @inheritdoc */
+    readonly name = "manage_skills";
+    /** @inheritdoc */
+    readonly displayName = "Manage Skills";
+    /** @inheritdoc */
+    readonly description: string;
+    /** @inheritdoc */
+    readonly category = "emergent";
+    /** @inheritdoc */
+    readonly hasSideEffects = true;
+    /** @inheritdoc */
+    readonly inputSchema: JSONSchemaObject;
+    /** Injected dependencies. */
+    private readonly deps;
+    /**
+     * Create a new ManageSkillsTool.
+     *
+     * @param deps - Injected dependencies including config, skill accessors,
+     *   and loader/unloader functions.
+     */
+    constructor(deps: ManageSkillsDeps);
+    /**
+     * Execute the requested skill management action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    execute(args: ManageSkillsInput, _context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Enable a skill after checking allowlist permissions.
+     *
+     * Allowlist resolution order:
+     * 1. `['*']` → always allowed
+     * 2. Exact skillId match → allowed
+     * 3. `'category:X'` in allowlist and skill.category === X → allowed
+     * 4. Skill's category already represented in active skills → allowed (same-category expansion)
+     * 5. Otherwise → `requires_approval` if requireApprovalForNewCategories, else `denied`
+     */
+    private handleEnable;
+    /**
+     * Resolve whether a skill is permitted by the allowlist configuration.
+     *
+     * @returns `'allowed'`, `'requires_approval'`, or `'denied'`
+     */
+    private resolvePermission;
+    /**
+     * Disable a skill, rejecting if it is locked.
+     */
+    private handleDisable;
+    /**
+     * Search for available skills by query string.
+     */
+    private handleSearch;
+    /**
+     * List currently active skills.
+     */
+    private handleList;
+}
+//# sourceMappingURL=ManageSkillsTool.d.ts.map

package/dist/emergent/ManageSkillsTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManageSkillsTool.d.ts","sourceRoot":"","sources":["../../src/emergent/ManageSkillsTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAMhC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,MAAM,EAAE;QACN;;;;;WAKG;QACH,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,mEAAmE;QACnE,+BAA+B,EAAE,OAAO,CAAC;KAC1C,CAAC;IACF,yDAAyD;IACzD,eAAe,EAAE,MAAM,eAAe,EAAE,CAAC;IACzC,6DAA6D;IAC7D,eAAe,EAAE,MAAM,MAAM,EAAE,CAAC;IAChC,yEAAyE;IACzE,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACpD,+CAA+C;IAC/C,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,2DAA2D;IAC3D,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,iBAAiB,EAAE,CAAC;CACtD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,CAAC;IAC/D,kBAAkB;IAClB,QAAQ,CAAC,EAAE,wCAAwC;IAEnD,kBAAkB;IAClB,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,mBAAmB;IAEvC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,SAE2B;IAE/C,kBAAkB;IAClB,QAAQ,CAAC,QAAQ,cAAc;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,cAAc,QAAQ;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAkBpC;IAEF,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IAExC;;;;;OAKG;gBACS,IAAI,EAAE,gBAAgB;IAQlC;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAsB/B;;;;;;;;;OASG;YACW,YAAY;IAwD1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA+BzB;;OAEG;YACW,aAAa;IAuB3B;;OAEG;YACW,YAAY;IAe1B;;OAEG;YACW,UAAU;CAQzB"}

package/dist/emergent/ManageSkillsTool.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview ManageSkillsTool — ITool implementation that enables agents to
+ * dynamically enable, disable, and search for skills at runtime.
+ *
+ * @module @framers/agentos/emergent/ManageSkillsTool
+ *
+ * Agents call `manage_skills` to self-modify their active skill set. The tool
+ * enforces an allowlist-based permission model:
+ * - Wildcard (`'*'`) allows all skills unconditionally.
+ * - Exact skill ID matches are always permitted.
+ * - Category-based allowlist entries (`'category:X'`) permit any skill in that category.
+ * - Same-category expansion: if any skill in category X is already active, other
+ *   skills in X are also permitted without explicit allowlist entry.
+ * - New categories may require approval when `requireApprovalForNewCategories` is set.
+ *
+ * Locked skills cannot be disabled.
+ */
+// ============================================================================
+// TOOL IMPLEMENTATION
+// ============================================================================
+/**
+ * ITool implementation enabling agents to dynamically manage their skill set
+ * at runtime, subject to allowlist and lock constraints.
+ *
+ * @example
+ * ```ts
+ * const tool = new ManageSkillsTool({
+ *   config: { allowlist: ['*'], requireApprovalForNewCategories: false },
+ *   getActiveSkills: () => agent.skills,
+ *   getLockedSkills: () => ['core-reasoning'],
+ *   loadSkill: (id) => skillRegistry.load(id),
+ *   unloadSkill: (id) => skillRegistry.unload(id),
+ *   searchSkills: (q) => skillRegistry.search(q),
+ * });
+ * ```
+ */
+export class ManageSkillsTool {
+    /**
+     * Create a new ManageSkillsTool.
+     *
+     * @param deps - Injected dependencies including config, skill accessors,
+     *   and loader/unloader functions.
+     */
+    constructor(deps) {
+        /** @inheritdoc */
+        this.id = 'com.framers.emergent.manage-skills';
+        /** @inheritdoc */
+        this.name = 'manage_skills';
+        /** @inheritdoc */
+        this.displayName = 'Manage Skills';
+        /** @inheritdoc */
+        this.description = 'Enable, disable, search, or list skills available to this agent. ' +
+            'Subject to allowlist and lock constraints.';
+        /** @inheritdoc */
+        this.category = 'emergent';
+        /** @inheritdoc */
+        this.hasSideEffects = true;
+        /** @inheritdoc */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['enable', 'disable', 'search', 'list'],
+                    description: 'The skill management action to perform.',
+                },
+                skillId: {
+                    type: 'string',
+                    description: 'Skill ID to enable or disable.',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query for finding skills.',
+                },
+            },
+            required: ['action'],
+        };
+        this.deps = deps;
+    }
+    // --------------------------------------------------------------------------
+    // EXECUTE
+    // --------------------------------------------------------------------------
+    /**
+     * Execute the requested skill management action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    async execute(args, _context) {
+        switch (args.action) {
+            case 'enable':
+                return this.handleEnable(args.skillId);
+            case 'disable':
+                return this.handleDisable(args.skillId);
+            case 'search':
+                return this.handleSearch(args.query);
+            case 'list':
+                return this.handleList();
+            default:
+                return {
+                    success: false,
+                    error: `Unknown action "${args.action}". Must be one of: enable, disable, search, list`,
+                };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // ACTION HANDLERS
+    // --------------------------------------------------------------------------
+    /**
+     * Enable a skill after checking allowlist permissions.
+     *
+     * Allowlist resolution order:
+     * 1. `['*']` → always allowed
+     * 2. Exact skillId match → allowed
+     * 3. `'category:X'` in allowlist and skill.category === X → allowed
+     * 4. Skill's category already represented in active skills → allowed (same-category expansion)
+     * 5. Otherwise → `requires_approval` if requireApprovalForNewCategories, else `denied`
+     */
+    async handleEnable(skillId) {
+        if (!skillId) {
+            return { success: false, error: 'skillId is required for the enable action' };
+        }
+        // Load the skill first to get its metadata
+        let skill;
+        try {
+            skill = await this.deps.loadSkill(skillId);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Failed to load skill "${skillId}": ${err.message ?? String(err)}`,
+            };
+        }
+        // Resolve allowlist permission
+        const permissionResult = this.resolvePermission(skill);
+        if (permissionResult === 'allowed') {
+            return {
+                success: true,
+                output: {
+                    status: 'enabled',
+                    skill: { skillId: skill.skillId, name: skill.name, category: skill.category },
+                },
+            };
+        }
+        // Not allowed — unload the skill we speculatively loaded
+        try {
+            this.deps.unloadSkill(skillId);
+        }
+        catch {
+            // Best-effort unload; skill may not have been fully registered
+        }
+        if (permissionResult === 'requires_approval') {
+            return {
+                success: true,
+                output: {
+                    status: 'requires_approval',
+                    skillId,
+                    category: skill.category,
+                    reason: `Skill category "${skill.category}" is new and requires approval.`,
+                },
+            };
+        }
+        return {
+            success: false,
+            error: `Skill "${skillId}" is not permitted by the allowlist.`,
+        };
+    }
+    /**
+     * Resolve whether a skill is permitted by the allowlist configuration.
+     *
+     * @returns `'allowed'`, `'requires_approval'`, or `'denied'`
+     */
+    resolvePermission(skill) {
+        const { allowlist, requireApprovalForNewCategories } = this.deps.config;
+        // 1. Wildcard
+        if (allowlist.includes('*')) {
+            return 'allowed';
+        }
+        // 2. Exact skill ID match
+        if (allowlist.includes(skill.skillId)) {
+            return 'allowed';
+        }
+        // 3. Category-based allowlist entry
+        if (allowlist.includes(`category:${skill.category}`)) {
+            return 'allowed';
+        }
+        // 4. Same-category expansion: category already represented in active skills
+        const activeSkills = this.deps.getActiveSkills();
+        const activeCategories = new Set(activeSkills.map((s) => s.category));
+        if (activeCategories.has(skill.category)) {
+            return 'allowed';
+        }
+        // 5. Otherwise — requires approval or denied
+        return requireApprovalForNewCategories ? 'requires_approval' : 'denied';
+    }
+    /**
+     * Disable a skill, rejecting if it is locked.
+     */
+    async handleDisable(skillId) {
+        if (!skillId) {
+            return { success: false, error: 'skillId is required for the disable action' };
+        }
+        const lockedSkills = this.deps.getLockedSkills();
+        if (lockedSkills.includes(skillId)) {
+            return {
+                success: false,
+                error: `Skill "${skillId}" is locked and cannot be disabled.`,
+            };
+        }
+        this.deps.unloadSkill(skillId);
+        return {
+            success: true,
+            output: { status: 'disabled', skillId },
+        };
+    }
+    /**
+     * Search for available skills by query string.
+     */
+    async handleSearch(query) {
+        if (!query) {
+            return { success: false, error: 'query is required for the search action' };
+        }
+        const results = this.deps.searchSkills(query);
+        return {
+            success: true,
+            output: { results },
+        };
+    }
+    /**
+     * List currently active skills.
+     */
+    async handleList() {
+        const skills = this.deps.getActiveSkills();
+        return {
+            success: true,
+            output: { skills },
+        };
+    }
+}
+//# sourceMappingURL=ManageSkillsTool.js.map

package/dist/emergent/ManageSkillsTool.js.map

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

package/dist/emergent/PersonalityMutationStore.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview SQLite persistence for personality mutations with
+ * Ebbinghaus-style strength decay.
+ *
+ * Mutations persist across sessions and gradually fade toward baseline
+ * unless reinforced by repeated adaptation. The ConsolidationLoop calls
+ * {@link PersonalityMutationStore.decayAll} each cycle to reduce mutation
+ * strengths; mutations whose strength drops below the 0.1 threshold are
+ * pruned automatically.
+ *
+ * Uses the same {@link IStorageAdapter} interface as EmergentToolRegistry,
+ * keeping storage concerns decoupled from specific SQLite drivers.
+ *
+ * @module @framers/agentos/emergent/PersonalityMutationStore
+ */
+import type { IStorageAdapter } from './EmergentToolRegistry.js';
+/**
+ * A single persisted personality mutation record.
+ *
+ * Represents a specific HEXACO trait adjustment made by the agent, along with
+ * its current strength (which decays over time) and the reasoning that
+ * motivated the change.
+ */
+export interface PersonalityMutation {
+    /** Unique mutation identifier (format: `pm_<timestamp>_<random>`). */
+    id: string;
+    /** The agent that made this mutation. */
+    agentId: string;
+    /** The HEXACO trait that was mutated (e.g., `'openness'`, `'conscientiousness'`). */
+    trait: string;
+    /** The signed delta applied to the trait value. Positive = increase, negative = decrease. */
+    delta: number;
+    /** Free-text reasoning explaining why the agent chose to mutate this trait. */
+    reasoning: string;
+    /** The trait value before this mutation was applied. */
+    baselineValue: number;
+    /** The trait value after this mutation was applied. */
+    mutatedValue: number;
+    /**
+     * Current strength of this mutation in the range (0, 1].
+     *
+     * Starts at 1.0 when recorded and decays each consolidation cycle.
+     * When strength drops to 0.1 or below, the mutation is pruned.
+     */
+    strength: number;
+    /** Unix epoch millisecond timestamp of when this mutation was recorded. */
+    createdAt: number;
+}
+/**
+ * Input parameters for recording a new personality mutation.
+ *
+ * The `strength` and `createdAt` fields are set automatically by the store
+ * (1.0 and `Date.now()` respectively).
+ */
+export interface RecordMutationInput {
+    /** The agent making the mutation. */
+    agentId: string;
+    /** The HEXACO trait being mutated. */
+    trait: string;
+    /** The signed delta to apply. */
+    delta: number;
+    /** Free-text reasoning for the mutation. */
+    reasoning: string;
+    /** The trait value before mutation. */
+    baselineValue: number;
+    /** The trait value after mutation. */
+    mutatedValue: number;
+}
+/**
+ * Result of a decay cycle, reporting how many mutations were weakened
+ * and how many were pruned (deleted) for falling below the threshold.
+ */
+export interface DecayResult {
+    /** Number of mutations whose strength was reduced but still above threshold. */
+    decayed: number;
+    /** Number of mutations deleted for falling at or below the 0.1 threshold. */
+    pruned: number;
+}
+/**
+ * SQLite-backed persistence layer for personality mutations with decay.
+ *
+ * Follows the same `ensureSchema()` pattern as {@link EmergentToolRegistry}:
+ * a cached promise guards against concurrent DDL execution, and all DML
+ * methods await schema readiness before proceeding.
+ *
+ * @example
+ * ```ts
+ * const store = new PersonalityMutationStore(sqliteAdapter);
+ *
+ * // Record a mutation
+ * const id = await store.record({
+ *   agentId: 'agent-42',
+ *   trait: 'openness',
+ *   delta: 0.1,
+ *   reasoning: 'User prefers creative responses',
+ *   baselineValue: 0.7,
+ *   mutatedValue: 0.8,
+ * });
+ *
+ * // Get strength-weighted effective deltas
+ * const deltas = await store.getEffectiveDeltas('agent-42');
+ * // => { openness: 0.1 }  (strength is 1.0 initially)
+ *
+ * // Decay all mutations by 5%
+ * const { decayed, pruned } = await store.decayAll(0.05);
+ * ```
+ */
+export declare class PersonalityMutationStore {
+    /** The underlying SQLite storage adapter. */
+    private readonly db;
+    /**
+     * Cached schema initialization promise.
+     * Ensures DDL runs exactly once, even under concurrent access.
+     */
+    private schemaReady;
+    /**
+     * Create a new PersonalityMutationStore.
+     *
+     * @param db - A storage adapter implementing the {@link IStorageAdapter}
+     *   interface. The same adapter used by EmergentToolRegistry can be reused.
+     */
+    constructor(db: IStorageAdapter);
+    /**
+     * Idempotent schema initialization.
+     *
+     * Creates the `personality_mutations` table and its agent/trait index if
+     * they don't already exist. Uses the adapter's `exec()` method when
+     * available (for multi-statement DDL), falling back to individual `run()`
+     * calls for adapters that don't support it.
+     *
+     * @returns A promise that resolves when the schema is ready.
+     */
+    private ensureSchema;
+    /**
+     * Record a new personality mutation.
+     *
+     * Inserts a mutation record with initial strength of 1.0 and the current
+     * timestamp. The mutation ID is generated deterministically from the
+     * current time and a random suffix.
+     *
+     * @param input - The mutation parameters (agent, trait, delta, reasoning, values).
+     * @returns The generated mutation ID.
+     */
+    record(input: RecordMutationInput): Promise<string>;
+    /**
+     * Load all active mutations for a given agent.
+     *
+     * Returns only mutations whose strength is above the 0.1 pruning threshold,
+     * ordered by creation time (newest first).
+     *
+     * @param agentId - The agent whose mutations to load.
+     * @returns An array of {@link PersonalityMutation} records.
+     */
+    loadForAgent(agentId: string): Promise<PersonalityMutation[]>;
+    /**
+     * Compute the effective (strength-weighted) delta for each trait.
+     *
+     * For each active mutation, multiplies the raw delta by the mutation's
+     * current strength, then sums per trait. This gives a realistic picture
+     * of how much each trait has drifted from baseline, accounting for decay.
+     *
+     * @param agentId - The agent whose effective deltas to compute.
+     * @returns A map of trait name to effective delta (sum of `delta * strength`).
+     */
+    getEffectiveDeltas(agentId: string): Promise<Record<string, number>>;
+    /**
+     * Decay all active mutations by the given rate and prune expired ones.
+     *
+     * For each mutation with strength above 0.1:
+     * - Subtracts `rate` from its strength.
+     * - If the new strength is at or below 0.1, the mutation is deleted (pruned).
+     * - Otherwise, the strength is updated in place.
+     *
+     * This implements Ebbinghaus-style forgetting: mutations that aren't
+     * reinforced by repeated adaptation gradually fade away.
+     *
+     * @param rate - The amount to subtract from each mutation's strength.
+     *   Typically 0.05 (the default from SelfImprovementConfig).
+     * @returns A {@link DecayResult} with counts of decayed and pruned mutations.
+     */
+    decayAll(rate: number): Promise<DecayResult>;
+}
+//# sourceMappingURL=PersonalityMutationStore.d.ts.map

package/dist/emergent/PersonalityMutationStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalityMutationStore.d.ts","sourceRoot":"","sources":["../../src/emergent/PersonalityMutationStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAMjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IAEX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IAEd,6FAA6F;IAC7F,KAAK,EAAE,MAAM,CAAC;IAEd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IAEtB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAEhB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,wBAAwB;IACnC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkB;IAErC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA8B;IAEjD;;;;;OAKG;gBACS,EAAE,EAAE,eAAe;IAQ/B;;;;;;;;;OASG;YACW,YAAY;IAoC1B;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BzD;;;;;;;;OAQG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAyBnE;;;;;;;;;OASG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAe1E;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CA4BnD"}