@lmzhen/dsh-evolution-core 0.1.0-rc.1

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-core";
+const name = "evolution-core-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/curator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Deterministic skill curator: active → stale → archived transitions.
+ * Pure function; file moves are performed by SkillLibrary.
+ */
+import type { UsageMap } from './usage.ts';
+export interface CuratorConfig {
+    staleAfterDays: number;
+    archiveAfterDays: number;
+    /** Shorter stale threshold for quality-warned skills; archive threshold never changes. */
+    qualityWarnStaleAfterDays?: number;
+    /** Explicit skill names never considered for lifecycle transitions. */
+    excludeSkillNames?: ReadonlySet<string>;
+    /** When true, usage records without created_by='agent' also enter the lifecycle. */
+    manageUnmanaged?: boolean;
+}
+export interface CuratorTransition {
+    name: string;
+    from: 'active' | 'stale' | 'archived';
+    to: 'stale' | 'archived' | 'active';
+    reason: string;
+}
+export interface CuratorResult {
+    transitions: CuratorTransition[];
+    archive: string[];
+    reactivate: string[];
+    markStale: string[];
+}
+export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
+export interface CuratorArchivedSkill {
+    name: string;
+    path: string;
+    reason: string;
+}
+export interface CuratorFailedSkill {
+    name: string;
+    reason: string;
+}
+export interface CuratorRunReport {
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    staleCandidates: string[];
+    llmNominations: string[];
+    archiveCandidates: string[];
+    archived: CuratorArchivedSkill[];
+    failed: CuratorFailedSkill[];
+    snapshotPath?: string;
+}
+export interface CuratorReportInput {
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    staleCandidates: readonly string[];
+    llmNominations: readonly string[];
+    archiveCandidates: readonly string[];
+    archived: readonly CuratorArchivedSkill[];
+    failed: readonly CuratorFailedSkill[];
+    snapshotPath?: string;
+}
+export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;
+export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date): CuratorResult;
+//# sourceMappingURL=curator.d.ts.map

package/lib/types/events.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Durable session events emitted by the evolution family.
+ * These are non-surface events: they never enter model history, but make
+ * self-evolution activity replayable and observable by UI/projections.
+ */
+export interface EvolutionReviewScheduledEvent {
+    kind: 'memory' | 'skill' | 'combined';
+    toolCalls: number;
+    userChars: number;
+    assistantChars: number;
+}
+export interface EvolutionPlanAppliedEvent {
+    planId: string;
+    /** Stable fingerprint of the policy snapshot that produced this plan. */
+    policyFingerprint?: string | undefined;
+    memoryApplied: number;
+    skillApplied: number;
+    rejectedOps: number;
+    evidenceQuotes?: number | undefined;
+    estimatedInputChars?: number | undefined;
+}
+export interface EvolutionSkillMutatedEvent {
+    action: string;
+    name: string;
+    filePath?: string;
+    archivedPath?: string;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'evolution/review-scheduled': EvolutionReviewScheduledEvent;
+        'evolution/plan-applied': EvolutionPlanAppliedEvent;
+        'evolution/skill-mutated': EvolutionSkillMutatedEvent;
+    }
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'evolution/skill-mutated'(event: EvolutionSkillMutatedEvent): void;
+    }
+}
+//# sourceMappingURL=events.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared library for the dsh-evolution plugin family.
+ *
+ * Pure stores, prompts, signals, lifecycle logic, threat scanning, IO seam
+ * types, and session-event augmentations. This package owns no Cordis plugin
+ * entry of its own; consumers import named exports from the package root so
+ * published npm bundles never depend on source subpaths.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+export * from './curator.ts';
+export * from './events.ts';
+export * from './io.ts';
+export * from './memory-store.ts';
+export * from './prompts.ts';
+export * from './signals.ts';
+export * from './skill-store.ts';
+export * from './state-store.ts';
+export * from './threats.ts';
+export * from './usage.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-core-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/io.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structural IO seam for the legacy facade stores.
+ *
+ * The facade accepts any object exposing this small async file-tree surface.
+ * Native DSH packages pass `ctx.evolutionIo.provider()`; standalone consumers
+ * (and the facade's own tests) can use `nodeEvolutionIo`.
+ */
+export interface EvolutionIoLike {
+    readText(path: string): Promise<string | null>;
+    writeText(path: string, content: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    list(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    rename(path: string, destination: string): Promise<void>;
+    copy(path: string, destination: string): Promise<void>;
+}
+/** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
+export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
+export declare function nodeEvolutionIo(): EvolutionIoLike;
+/** Absolute path helper kept separate so stores stay platform-correct. */
+export declare function childPath(parent: string, ...parts: string[]): string;
+//# sourceMappingURL=io.d.ts.map

package/lib/types/memory-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * File-backed durable memory with Hermes-compatible semantics.
+ * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
+ */
+import { type EvolutionIoLike } from './io.ts';
+export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+export type MemoryTarget = 'memory' | 'user';
+export interface MemoryOperation {
+    action: 'add' | 'replace' | 'remove';
+    facts?: string | undefined;
+    old_text?: string | undefined;
+}
+export interface MemoryApplyResult {
+    ok: boolean;
+    message: string;
+    entries: string[];
+    chars: number;
+    limit: number;
+}
+export declare function memoryRoot(env?: NodeJS.ProcessEnv): string;
+export interface MemoryStoreOptions {
+    memoryCharLimit?: number;
+    userCharLimit?: number;
+    addDatePrefix?: boolean;
+    root?: string;
+    maxConsolidationFailures?: number;
+    io?: EvolutionIoLike;
+}
+export type { EvolutionIoLike };
+export declare class MemoryStore {
+    readonly memoryLimit: number;
+    readonly userLimit: number;
+    readonly addDatePrefix: boolean;
+    readonly root: string;
+    private readonly maxFailures;
+    private readonly io;
+    private failureCount;
+    constructor(options?: MemoryStoreOptions);
+    limitFor(target: MemoryTarget): number;
+    read(target: MemoryTarget): Promise<string[]>;
+    write(target: MemoryTarget, entries: string[]): Promise<void>;
+    resetFailures(): void;
+    private failure;
+    add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
+    replace(target: MemoryTarget, oldText: string, facts: string): Promise<MemoryApplyResult>;
+    remove(target: MemoryTarget, oldText: string): Promise<MemoryApplyResult>;
+    private mutate;
+    applyBatch(target: MemoryTarget, operations: MemoryOperation[]): Promise<MemoryApplyResult>;
+    renderContext(): Promise<string>;
+    snapshot(): Promise<{
+        memory: string[];
+        user: string[];
+    }>;
+    restoreSnapshot(snapshot: {
+        memory: string[];
+        user: string[];
+    }): Promise<void>;
+    detectDrift(target: MemoryTarget): Promise<boolean>;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/lib/types/prompts.d.ts

@@ -0,0 +1,16 @@
+export declare const PROMPT_BUNDLE_ID = "dsh-evolution@1";
+export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
+export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 most sessions produce at least one skill update, even if small.\n\nTarget shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.\n\nSignals that warrant action:\n- The user corrected your style, tone, format, verbosity, workflow, or approach.\n- A non-trivial technique, fix, workaround, or debugging path emerged.\n- A loaded skill turned out wrong, missing, or outdated \u2014 patch it now.\n\nPreference order:\n1. Patch a skill that was loaded or read this session.\n2. Patch an existing umbrella skill.\n3. Add references/, templates/, or scripts/ support under an existing skill.\n4. Create a new class-level umbrella skill only when nothing fits.\n\nProtected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.\n\nDo NOT capture:\n- Environment-dependent failures (missing binaries, unconfigured credentials).\n- Negative claims about tools (\"browser tools do not work\").\n- Transient errors that resolved during the session.\n- One-off task narratives.\n\nIf a tool failed because of setup state, capture the FIX under an existing setup skill \u2014 never \"this tool does not work\" as a standalone constraint.\n\n\"Nothing to save.\" is a real option but should NOT be the default.";
+export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things.\n\n**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.\n\nAct on whichever dimension has real signal. If genuinely nothing stands out on either, say \"Nothing to save.\" and stop \u2014 but don't reach for that conclusion as a default.";
+export declare const CURATOR_PROMPT = "You are the skill curator. Maintain a healthy, class-level skill library.\n\nRules:\n1. NEVER hard-delete a skill. Archive is the maximum destructive action.\n2. Do not touch bundled, hub-installed, or pinned skills.\n3. Do not archive recently-created or never-used skills without strong evidence.\n4. Prefer merging narrow skills into class-level umbrellas.\n5. Before archiving a merged skill, ensure its unique content was preserved.\n\nProduce a YAML summary:\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence>";
+export declare function reviewPrompt(kind: 'memory' | 'skill' | 'combined'): string;
+export interface PromptBundle {
+    id: string;
+    version: number;
+    prompts: Readonly<Record<string, string>>;
+    sha256: string;
+}
+export declare const PROMPT_BUNDLE: PromptBundle;
+export declare function verifyPromptBundle(bundle?: PromptBundle): boolean;
+export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.";
+//# sourceMappingURL=prompts.d.ts.map

package/lib/types/signals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Deterministic review signal gate.
+ *
+ * Scans a DSH session event log for durable learning signals before any LLM
+ * is spent. `turn/end` calls `observeTurn`; the returned review kind is
+ * accumulated until a configured interval fires.
+ */
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+export type ReviewKind = 'memory' | 'skill' | 'combined';
+export interface SignalConfig {
+    memoryInterval: number;
+    skillInterval: number;
+    substantiveMinToolCalls: number;
+    substantiveMinUserChars: number;
+    substantiveMinAgentChars: number;
+}
+export interface TurnSignals {
+    substantive: boolean;
+    toolCalls: number;
+    userChars: number;
+    assistantChars: number;
+    memorySignal: boolean;
+    skillSignal: boolean;
+}
+export interface ReviewState {
+    turnsSinceMemory: number;
+    turnsSinceSkill: number;
+    lastTurn: number;
+}
+/** Fold one session event into the current turn observation. */
+export declare function observeEvent(signal: TurnSignals, event: SessionEvent): void;
+/** Compute review cadence after `turn/end`. */
+export declare function advanceReview(state: ReviewState, turn: number, signal: TurnSignals, config: SignalConfig): ReviewKind | null;
+/** Fold all events between two sequence boundaries into one TurnSignals. */
+export declare function foldTurn(session: Session, fromSeq: number): TurnSignals;
+//# sourceMappingURL=signals.d.ts.map

package/lib/types/skill-store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Skill library management for the self-evolution plugin.
+ *
+ * Skills live under `$DSH_HOME/skills` (`~/.dsh/skills` by default), matching
+ * the default dsh skill-filesystem user root. The plugin only manages skills
+ * it created unless a `.hermes-managed` marker opts a skill in. Archival is a
+ * move to `.archive/` — never a hard delete.
+ */
+import { type EvolutionIoLike } from './io.ts';
+export declare const SKILL_NAME_RE: RegExp;
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+export declare const MAX_DESCRIPTION_LENGTH = 1024;
+export declare const MAX_SKILL_CONTENT_CHARS = 100000;
+export declare const MAX_SKILL_FILE_BYTES = 1048576;
+export interface SkillLimits {
+    maxNameLength: number;
+    maxDescriptionLength: number;
+    maxSkillContentChars: number;
+    maxSkillFileBytes: number;
+}
+export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
+export declare const SUPPORT_DIRS: readonly ["references", "templates", "scripts", "assets"];
+export interface SkillSummary {
+    name: string;
+    description: string;
+    path: string;
+    protectedBy: string | null;
+    managed: boolean;
+    archived: boolean;
+}
+export interface SkillActionResult {
+    ok: boolean;
+    message: string;
+    path?: string;
+}
+export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
+export interface Frontmatter {
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export declare function parseFrontmatter(content: string): {
+    frontmatter: Frontmatter;
+    body: string;
+} | null;
+export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits): string | null;
+export declare class SkillLibrary {
+    readonly root: string;
+    readonly limits: SkillLimits;
+    private readonly io;
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits);
+    list(): Promise<SkillSummary[]>;
+    read(name: string): Promise<string | null>;
+    writeProtection(name: string): Promise<string | null>;
+    deleteProtection(name: string): Promise<string | null>;
+    isManaged(name: string): Promise<boolean>;
+    create(name: string, content: string, origin: 'foreground' | 'background_review'): Promise<SkillActionResult>;
+    update(name: string, content: string): Promise<SkillActionResult>;
+    patch(name: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean): Promise<SkillActionResult>;
+    archive(name: string, absorbedInto?: string): Promise<SkillActionResult>;
+    writeSupportFile(name: string, filePath: string, content: string): Promise<SkillActionResult>;
+    removeSupportFile(name: string, filePath: string): Promise<SkillActionResult>;
+    snapshotAll(reason?: string): Promise<string>;
+    listSnapshots(): Promise<Array<{
+        path: string;
+        createdAt: string;
+        reason: string;
+    }>>;
+    restoreLatestSnapshot(): Promise<SkillActionResult>;
+}
+//# sourceMappingURL=skill-store.d.ts.map

package/lib/types/state-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Small crash-safe JSON state store for plugin-owned sidecar state.
+ * Writes are atomic (temp + rename). Reads are synchronous for startup use.
+ */
+export declare function evolutionHome(env?: NodeJS.ProcessEnv): string;
+export declare class JsonState<T> {
+    private readonly initial;
+    readonly path: string;
+    private value;
+    constructor(name: string, initial: T, env?: NodeJS.ProcessEnv);
+    private loadSync;
+    get(): T;
+    set(value: T): void;
+    update(mutator: (value: T) => void): void;
+    flush(): Promise<void>;
+    /** Merge-on-load helper for persisted maps/records. */
+    reload(): Promise<void>;
+}
+//# sourceMappingURL=state-store.d.ts.map

package/lib/types/threats.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Threat scanning for agent-authored memory and skill content.
+ *
+ * Ported as a small, dependency-free subset of Hermes Agent's
+ * `tools/threat_patterns.py` + hermes-claw `threats.ts`. The policy is the
+ * load-bearing part: ANY in-scope hit blocks. Severity and category are
+ * metadata for diagnostics only.
+ */
+export type ThreatScope = 'all' | 'context' | 'strict';
+export interface ThreatFinding {
+    label: string;
+    category: string;
+    scope: ThreatScope;
+}
+/**
+ * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
+ */
+export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number): ThreatFinding[];
+/** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
+export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number): {
+    blocked: boolean;
+    findings: ThreatFinding[];
+};
+/** User-facing block message for memory writes. */
+export declare function scanMemoryThreats(text: string, maxScanChars?: number): string | null;
+/** User-facing block message for skill content writes. */
+export declare function scanContentThreats(text: string, maxScanChars?: number): string | null;
+//# sourceMappingURL=threats.d.ts.map

package/lib/types/usage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Skill usage telemetry sidecar: `$DSH_HOME/skills/.usage.json`.
+ * Format-compatible with Hermes Agent / hermes-claw core fields.
+ */
+import { type EvolutionIoLike } from './io.ts';
+export type SkillState = 'active' | 'stale' | 'archived';
+export interface UsageRecord {
+    created_by: string | null;
+    use_count: number;
+    view_count: number;
+    patch_count: number;
+    last_used_at: string | null;
+    last_viewed_at: string | null;
+    last_patched_at: string | null;
+    created_at: string;
+    state: SkillState;
+    pinned: boolean;
+    archived_at: string | null;
+    quality_score?: number;
+    quality_warn?: boolean;
+}
+export type UsageMap = Map<string, UsageRecord>;
+export declare function usageFile(root: string): string;
+export declare function emptyRecord(): UsageRecord;
+export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
+export declare function saveUsage(root: string, map: UsageMap, io?: EvolutionIoLike): Promise<void>;
+export declare function getRecord(map: UsageMap, name: string): UsageRecord;
+export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
+export declare function bumpUse(map: UsageMap, name: string, when?: Date): void;
+export declare function bumpPatch(map: UsageMap, name: string, when?: Date): void;
+export declare function markAgentCreated(map: UsageMap, name: string): void;
+export declare function latestActivityAt(record: UsageRecord): string | null;
+//# sourceMappingURL=usage.d.ts.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lmzhen/dsh-evolution-core",
+  "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
+  "version": "0.1.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-evolution-core"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  }
+}