dsh-continual-evolve 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Type model for the continual-evolution harness state.
+ *
+ * Design provenance: the state model follows the continual-harness design
+ * validated in prime-agent's `/refine` subsystem (MIT): versioned entries
+ * keyed by kind, an append-only refinement history carrying an evidence
+ * trail, atomic persistence, and deterministic inverse-op rollback. The
+ * code here is an original implementation, written for the DeepSeek Harness
+ * plugin surface.
+ */
+/** What a harness entry can be. */
+export type RefinementKind = "prompt" | "memory" | "skill" | "subagent";
+/** How an entry changes. */
+export type RefinementAction = "create" | "update" | "delete" | "archive";
+/** Where an entry lives: session-scoped or cross-session. */
+export type HarnessScope = "local" | "global";
+/**
+ * Metadata key recording which session an entry's content was distilled from
+ * (trajectory citation; see {@link EntrySource}).
+ */
+export declare const SOURCE_SESSION_KEY = "sourceSession";
+/**
+ * Metadata key recording the session-log event seqs (of the direct user
+ * messages) the entry cites as its source (trajectory citation).
+ */
+export declare const SOURCE_SEQS_KEY = "sourceSeqs";
+/**
+ * Metadata key recording when an entry was archived. Archived entries are
+ * hidden from injection but never deleted — the data stays in the store and
+ * the entry can be restored (unarchive) or rolled back like any other edit.
+ */
+export declare const ARCHIVED_AT_KEY = "archivedAt";
+/**
+ * True when the entry is archived (hidden from injection, restorable).
+ * Absent or empty archivedAt means the entry is active.
+ */
+export declare function isArchived(entry: HarnessEntry): boolean;
+/**
+ * Trajectory citation attached to newly created entries: the session the
+ * content came from and the seqs of the direct user messages it was
+ * distilled from. Both fields are optional — when they cannot be determined
+ * the citation is simply omitted (never an error).
+ */
+export interface EntrySource {
+    sessionId?: string;
+    /** Event seqs of the source user messages, in log order. */
+    seqs?: number[];
+}
+/** A single persisted harness entry. */
+export interface HarnessEntry {
+    id: string;
+    kind: RefinementKind;
+    title: string;
+    content: string;
+    path: string;
+    scope: HarnessScope;
+    /** Skill entries carry an executable contract; see {@link PythonReference}. */
+    reference: Record<string, unknown>;
+    /** Skill entries declare their accepted inputs here. */
+    arguments: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    source: "evolve";
+    created_at: string;
+    updated_at: string;
+    version: number;
+}
+/** One entry of the append-only refinement history (the evidence trail). */
+export interface HarnessRefinementEvent {
+    id: string;
+    trigger: string;
+    changes: string[];
+    /** Where the trajectory evidence for this refinement lives (e.g. seq ranges). */
+    evidence: string;
+    /** The falsifiable expectation recorded with the edit. */
+    outcome: string;
+    created_at: string;
+}
+/** The whole harness state file. */
+export interface HarnessState {
+    schema: number;
+    entries: Record<RefinementKind, Record<string, HarnessEntry>>;
+    refinements: HarnessRefinementEvent[];
+}
+/** A model-proposed edit, before validation and application. */
+export interface RefinementEdit {
+    action: RefinementAction;
+    kind: RefinementKind;
+    id?: string;
+    title?: string;
+    content?: string;
+    path?: string;
+    reference?: Record<string, unknown>;
+    arguments?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    reason?: string;
+}
+/** The structured output of a planning pass. */
+export interface RefinementProposal {
+    summary: string;
+    rationale: string;
+    edits: RefinementEdit[];
+    expectedOutcome: string;
+}
+/** An edit after the apply pass: before/after snapshots and outcome per edit. */
+export interface AppliedRefinementEdit extends RefinementEdit {
+    id: string;
+    before?: HarnessEntry;
+    after?: HarnessEntry;
+    applied: boolean;
+    error?: string;
+}
+/** The result of applying one refinement. */
+export interface RefinementResult {
+    id: string;
+    summary: string;
+    rationale: string;
+    expectedOutcome: string;
+    appliedEdits: AppliedRefinementEdit[];
+    harnessStatePath: string;
+    rollbackOf?: string;
+    scope?: HarnessScope;
+}
+/** The executable contract a skill entry must carry (python REPL skills). */
+export interface PythonReference {
+    type: "python";
+    import?: string;
+    python_import?: string;
+    callable?: string;
+    call_pattern?: string;
+}
+/** A stable id derived from a title. */
+export declare function slug(raw: string, fallback: string): string;
+/** Fresh empty state with the current schema version. */
+export declare function emptyHarnessState(): HarnessState;
+/** Deep clone helper (state is plain JSON data). */
+export declare function cloneEntry(entry: HarnessEntry | undefined): HarnessEntry | undefined;
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,62 @@
+/**
+ * Type model for the continual-evolution harness state.
+ *
+ * Design provenance: the state model follows the continual-harness design
+ * validated in prime-agent's `/refine` subsystem (MIT): versioned entries
+ * keyed by kind, an append-only refinement history carrying an evidence
+ * trail, atomic persistence, and deterministic inverse-op rollback. The
+ * code here is an original implementation, written for the DeepSeek Harness
+ * plugin surface.
+ */
+/**
+ * Metadata key recording which session an entry's content was distilled from
+ * (trajectory citation; see {@link EntrySource}).
+ */
+export const SOURCE_SESSION_KEY = "sourceSession";
+/**
+ * Metadata key recording the session-log event seqs (of the direct user
+ * messages) the entry cites as its source (trajectory citation).
+ */
+export const SOURCE_SEQS_KEY = "sourceSeqs";
+/**
+ * Metadata key recording when an entry was archived. Archived entries are
+ * hidden from injection but never deleted — the data stays in the store and
+ * the entry can be restored (unarchive) or rolled back like any other edit.
+ */
+export const ARCHIVED_AT_KEY = "archivedAt";
+/**
+ * True when the entry is archived (hidden from injection, restorable).
+ * Absent or empty archivedAt means the entry is active.
+ */
+export function isArchived(entry) {
+    const value = entry.metadata[ARCHIVED_AT_KEY];
+    return typeof value === "string" && value.length > 0;
+}
+/** A stable id derived from a title. */
+export function slug(raw, fallback) {
+    const normalized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 80);
+    return normalized || fallback;
+}
+/** Fresh empty state with the current schema version. */
+export function emptyHarnessState() {
+    return {
+        schema: 1,
+        entries: {
+            prompt: {},
+            memory: {},
+            skill: {},
+            subagent: {},
+        },
+        refinements: [],
+    };
+}
+/** Deep clone helper (state is plain JSON data). */
+export function cloneEntry(entry) {
+    return entry ? JSON.parse(JSON.stringify(entry)) : undefined;
+}
+//# sourceMappingURL=types.js.map

package/lib/validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Code-enforced validation of model-proposed edits. Every rule here exists
+ * because the proposal is untrusted input: enum membership, immutability of
+ * the base system prompt, required fields per action, and the executable
+ * contract skill entries must carry.
+ */
+import type { RefinementEdit } from "./types.js";
+export declare const BASE_SYSTEM_PROMPT_ID = "base_system_prompt";
+/** Returns a human-readable failure reason, or undefined when the edit passes. */
+export declare function validateEdit(edit: RefinementEdit, computedId: string | undefined): string | undefined;
+//# sourceMappingURL=validate.d.ts.map

package/lib/validate.js

@@ -0,0 +1,55 @@
+const ACTIONS = new Set(["create", "update", "delete", "archive"]);
+const KINDS = new Set(["prompt", "memory", "skill", "subagent"]);
+export const BASE_SYSTEM_PROMPT_ID = "base_system_prompt";
+/** Returns a human-readable failure reason, or undefined when the edit passes. */
+export function validateEdit(edit, computedId) {
+    if (!ACTIONS.has(edit.action)) {
+        return `unsupported action ${String(edit.action)}`;
+    }
+    if (!KINDS.has(edit.kind)) {
+        return `unsupported kind ${String(edit.kind)}`;
+    }
+    if (edit.kind === "prompt" && (edit.id === BASE_SYSTEM_PROMPT_ID || computedId === BASE_SYSTEM_PROMPT_ID)) {
+        return "base system prompt is not editable";
+    }
+    if (edit.action !== "create" && !edit.id) {
+        return `${edit.action} requires id`;
+    }
+    // Archive only names an existing entry: no title/content payload, and the
+    // base system prompt stays immutable under every action.
+    if (edit.action === "archive") {
+        return undefined;
+    }
+    if (edit.action !== "delete" && (!edit.title || !edit.content)) {
+        return `${edit.action} requires title and content`;
+    }
+    if (edit.action !== "delete" && edit.kind === "skill") {
+        return validateSkillContract(edit);
+    }
+    return undefined;
+}
+function validateSkillContract(edit) {
+    if (edit.arguments === undefined) {
+        return "create/update skill requires arguments";
+    }
+    const reference = edit.reference;
+    if (!reference || typeof reference !== "object") {
+        return "create/update skill requires python reference";
+    }
+    const ref = reference;
+    if (ref.type !== "python") {
+        return "create/update skill reference.type must be python";
+    }
+    const hasImport = (typeof ref.import === "string" && ref.import.length > 0) ||
+        (typeof ref.python_import === "string" && ref.python_import.length > 0);
+    const hasCallable = (typeof ref.callable === "string" && ref.callable.length > 0) ||
+        (typeof ref.call_pattern === "string" && ref.call_pattern.length > 0);
+    if (!hasImport) {
+        return "create/update skill requires python import";
+    }
+    if (!hasCallable) {
+        return "create/update skill requires callable or call_pattern";
+    }
+    return undefined;
+}
+//# sourceMappingURL=validate.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "dsh-continual-evolve",
+  "version": "0.1.0",
+  "description": "Continual self-evolution plugin for DeepSeek Harness: versioned, auditable, rollback-safe harness state (prompt notes, memories, skills, subagent specs) refined from session trajectories.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.10.0",
+    "oxlint": "^0.16.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint src test",
+    "clean": "rm -rf lib"
+  }
+}