dsh-continual-evolve 0.1.0 → 0.2.0

package/lib/types.js

@@ -24,6 +24,25 @@ export const SOURCE_SEQS_KEY = "sourceSeqs";
  * the entry can be restored (unarchive) or rolled back like any other edit.
  */
 export const ARCHIVED_AT_KEY = "archivedAt";
+/**
+ * Metadata key stamped on a LOCAL entry that was promoted to the global
+ * store by a session wrap-up: the id of the global entry it became. Present
+ * means the entry's lifecycle is finished — it must not be offered for
+ * promotion again (the global copy is the live one, the local copy is a
+ * restorable trace).
+ */
+export const PROMOTED_TO_KEY = "promotedTo";
+/**
+ * Metadata key recording when a local entry was promoted to the global
+ * store (companion of {@link PROMOTED_TO_KEY}).
+ */
+export const PROMOTED_AT_KEY = "promotedAt";
+/**
+ * Metadata key stamped on a GLOBAL entry created by a session wrap-up
+ * promotion: `<sessionId>:<localEntryId>` — the反向 provenance link from the
+ * cross-session copy back to the session it was distilled from.
+ */
+export const SOURCED_FROM_KEY = "sourcedFromLocal";
 /**
  * True when the entry is archived (hidden from injection, restorable).
  * Absent or empty archivedAt means the entry is active.

package/lib/validate.js

@@ -1,3 +1,4 @@
+import { validateSkillEntryContent } from "./skillquality.js";
 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";
@@ -24,7 +25,30 @@ export function validateEdit(edit, computedId) {
         return `${edit.action} requires title and content`;
     }
     if (edit.action !== "delete" && edit.kind === "skill") {
-        return validateSkillContract(edit);
+        // Guidance skills are SKILL.md documents: no python reference (a
+        // reference on a guidance skill would be an invented contract) and
+        // no arguments contract. Executable skills keep the full contract.
+        if (edit.skill_kind === "guidance") {
+            if (edit.reference !== undefined && Object.keys(edit.reference).length > 0) {
+                return "guidance skill must not carry a python reference (it is a SKILL.md document, not an executable)";
+            }
+            if (edit.arguments !== undefined && Object.keys(edit.arguments).length > 0) {
+                return "guidance skill must not carry an arguments contract (only executable skills declare inputs)";
+            }
+        }
+        else {
+            const contractError = validateSkillContract(edit);
+            if (contractError)
+                return contractError;
+        }
+        // The entry body materializes as a SKILL.md under generated
+        // frontmatter; content-level mechanics (no shadowing `---`, no
+        // escaping resource refs) are code-enforced so a bad body never
+        // reaches the store (mirrors skill-creator's validate-frontmatter).
+        const contentProblems = validateSkillEntryContent(edit.content ?? "");
+        if (contentProblems.length > 0) {
+            return contentProblems.join("; ");
+        }
     }
     return undefined;
 }

package/lib/wrapup.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Session wrap-up: the lifecycle exit for a session's local harness entries.
+ *
+ * When a session ends, its local entries default to orphans: a later session
+ * (not on the parentSession chain) never sees them, and nothing promotes or
+ * archives them — the exploration results effectively "die" with the session.
+ * Wrap-up gives those entries a real exit:
+ *
+ * - cross-session-reusable content is classified `promote` and moved into the
+ *   global store (through the human approval gate — global is a governed
+ *   resource, exactly like skill proposals);
+ * - session-specific / superseded / already-covered content is classified
+ *   `archive` (hidden from injection, data stays restorable, rollbackable);
+ * - everything else is kept.
+ *
+ * Division of labor is deliberate: the mechanical audit proposes, the LLM
+ * classifies, the user approves, the code applies deterministically. The
+ * apply-side guard (`filterPromotable`) re-checks global coverage at apply
+ * time so a stale classification can never write a duplicate global entry.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { HarnessEntry, HarnessState, RefinementKind, RefinementProposal } from "./types.js";
+/** What should happen to one local entry at session end. */
+export type WrapupVerdict = "promote" | "archive" | "keep";
+/** A classified local entry: `key` matches one audited candidate exactly. */
+export interface WrapupItem {
+    /** `kind:id` of the candidate this verdict refers to. */
+    key: string;
+    verdict: WrapupVerdict;
+    reason: string;
+    /**
+     * Optional split-promotion payload (verdict "archive" only): the entry is
+     * archived as a whole, but a CLEANED cross-session-reusable part is
+     * offered for promotion — the durable fact distilled out of the mixed
+     * entry, with the ephemeral snapshot left behind in the archive.
+     */
+    promote?: {
+        title: string;
+        content: string;
+    };
+}
+/** A real global entry worth showing the assessor for the same topic. */
+export interface GlobalHint {
+    id: string;
+    title: string;
+}
+/** The model's full classification of a session's local entries. */
+export interface WrapupAssessment {
+    items: WrapupItem[];
+    rationale: string;
+}
+/** A local entry offered for assessment, plus its deterministic audit flags. */
+export interface WrapupCandidate {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    content: string;
+    path: string;
+    version: number;
+    metadata: Record<string, unknown>;
+    /**
+     * True when the global store already covers this topic by a STRONG
+     * signal: a title that normalizes equal to, or (beyond a length floor)
+     * contains, the candidate's title. Collisions on id alone with a wildly
+     * different title are deliberately NOT coverage — see {@link globalHintsFor}.
+     */
+    coveredGlobally: boolean;
+    /**
+     * Actual global entries that touch the same topic (same id, equal
+     * normalized title, or title overlap). Shown to the assessor so it judges
+     * against real titles instead of a bare boolean; a bare same-id collision
+     * shows up here precisely so the model can tell whether the global copy
+     * really covers the local content.
+     */
+    globalHints: GlobalHint[];
+}
+export declare function candidateKey(kind: RefinementKind, id: string): string;
+/**
+ * Deterministic global-coverage check (STRONG signal): the global store
+ * already covers a topic when it holds a title that normalizes equal to, or
+ * (beyond a length floor) contains, the candidate's normalized title.
+ * Archived global entries count too — the topic was already judged
+ * cross-session; a local duplicate would only re-sediment it.
+ *
+ * The bare same-id case is deliberately NOT coverage: ids are slugs derived
+ * from titles, so a real collision is usually caught by the title check
+ * below. A same-id entry with a wildly different title is a weak signal — the
+ * caller routes it through {@link globalHintsFor} for the assessor to judge
+ * against the actual global title (real case: local `memory` "用户产品愿景与
+ * 收入需求（本会话）" vs global `memory` "用户画像（持续更新）").
+ */
+export declare function globalCoverageDetected(globalState: HarnessState, kind: RefinementKind, entry: Pick<HarnessEntry, "id" | "title">): boolean;
+/**
+ * The actual global entries that touch the same topic as a local candidate:
+ * same id (regardless of title — the weak collision signal that is NOT
+ * coverage on its own), equal normalized title, or title overlap. The raw ids
+ * and titles let the assessor judge enrichment against real global content
+ * (does the global copy already hold what the local one adds?) rather than a
+ * bare boolean. Bounded: a handful of best matches, never the whole store.
+ */
+export declare function globalHintsFor(globalState: HarnessState, kind: RefinementKind, entry: Pick<HarnessEntry, "id" | "title">): GlobalHint[];
+/**
+ * The auditable local candidates of a session: every non-archived local
+ * entry that has not already been promoted (a promoted entry's lifecycle is
+ * finished — the global copy is the live one). Each carries its
+ * `coveredGlobally` flag so the assessor never wastes a promote on a topic
+ * the global store already owns.
+ */
+export declare function listLocalCandidates(state: HarnessState, globalState: HarnessState): WrapupCandidate[];
+/**
+ * Parse and validate the model's assessment JSON. Defense is mechanical:
+ * keys outside the candidate list are dropped, verdicts outside the enum
+ * collapse to "keep", and candidates the model omitted default to "keep" —
+ * a malformed reply can never change an entry's fate by itself.
+ *
+ * Split promotion (verdict "archive" with a `promote` sub-object): the
+ * sub-object is accepted ONLY on archive verdicts and ONLY when both cleaned
+ * title and content are non-empty strings — a dropped/malformed sub-object
+ * silently degrades to a plain archive (the entry is never half-promoted).
+ */
+export declare function parseWrapupAssessment(text: string, candidates: readonly WrapupCandidate[]): WrapupAssessment;
+export interface PromotableSplit {
+    /** Items that may be promoted: classified promote AND not covered globally. */
+    promotable: WrapupItem[];
+    /** Items classified promote but blocked by the deterministic guard, with why. */
+    skipped: {
+        key: string;
+        reason: string;
+    }[];
+}
+/**
+ * Apply-time deterministic guard: re-check every promote verdict against the
+ * global store right before it lands. The LLM classification may be stale
+ * (a gate ran while assessing) or wrong; this ensures a promote never writes
+ * a duplicate global entry. Pure and unit-tested.
+ */
+export declare function filterPromotable(items: readonly WrapupItem[], globalState: HarnessState, candidates: readonly WrapupCandidate[]): PromotableSplit;
+export interface ArchiveReviewSplit {
+    /** Archives that may proceed silently: topic already covered, no real
+     * distillation source, or the archive half of an already-approved split. */
+    silent: WrapupItem[];
+    /**
+     * Archives that would bury possibly-reusable content: not covered
+     * globally AND distilled from real user messages (sourceSeqs present).
+     * These MAY NOT archive silently — the command must get user
+     * confirmation first (the symmetric guard to filterPromotable: it stops
+     * over-archiving, not just over-writing).
+     */
+    review: WrapupItem[];
+}
+/**
+ * The symmetric archive guard. `filterPromotable` is one-directional: it
+ * stops the model from WRITING duplicate global entries, but nothing stopped
+ * an unfounded ARCHIVE from hiding content that was actually only local.
+ * Guard criteria: an archive needs user confirmation when it is NOT covered
+ * globally AND the entry carries a real distillation source (sourceSeqs /
+ * sourceSession — i.e. it was distilled from actual user messages, so it
+ * may hold reusable value). Operational/empty entries archive silently as
+ * before. Split archives (archive + promote sub-object) skip this check:
+ * their promotion already crosses a human approval gate, so the archive is
+ * the completion of an approved action, not a silent burial.
+ */
+export declare function needsArchiveReview(item: WrapupItem, candidate: WrapupCandidate): boolean;
+/** Partition archive items into silent vs review-required (see needsArchiveReview). */
+export declare function splitArchiveGuards(items: readonly WrapupItem[], candidates: readonly WrapupCandidate[]): ArchiveReviewSplit;
+/**
+ * Apply-time guard for a split promotion (archive + promote sub-object):
+ * the cleaned title must not duplicate a topic already covered globally. A
+ * duplicate split is dropped (the entry still archives plain) rather than
+ * half-promoting a redundancy.
+ */
+export declare function splitPromoteBlocked(item: WrapupItem, globalState: HarnessState, kind: RefinementKind): string | undefined;
+/**
+ * Shared proposal builders for a WHOLE promotion — used by both the
+ * `/evolve wrapup` command and the gate's local-fate dimension so the two
+ * paths apply IDENTICAL edits (global create + local retirement stamp).
+ *
+ * The local stamp is a factory: the `promotedTo` id is only known after the
+ * global create lands (validation may slugify the id), so the caller applies
+ * the global proposal first and stamps the local copy with the created id.
+ */
+export declare function wholePromoteProposals(item: WrapupItem, candidate: WrapupCandidate, sessionId: string): {
+    global: RefinementProposal;
+    localStamp: (createdId: string) => RefinementProposal;
+};
+/**
+ * Shared proposal builders for a SPLIT promotion (A-form): archive a mixed
+ * local entry but promote ONLY the cleaned durable part the model extracted.
+ * Same usage contract as {@link wholePromoteProposals}: apply the global
+ * create, then stamp the original local entry with the created id.
+ */
+export declare function splitPromoteProposals(item: WrapupItem, candidate: WrapupCandidate, sessionId: string): {
+    global: RefinementProposal;
+    localStamp: (createdId: string) => RefinementProposal;
+};
+export declare const WRAPUP_ASSESS_SYSTEM_PROMPT = "You are the /evolve session wrap-up assessor.\n\nA session is ending and its local harness entries need a fate. Classify each\nlisted entry exactly once:\n\n- \"promote\" \u2014 the content is a stable, durable, CROSS-SESSION reusable lesson:\n  a durable user preference, a project-level fact or convention, a reusable\n  procedure or skill. Future sessions would benefit from seeing it.\n- \"archive\" \u2014 the content is session-specific task progress, one-off noise,\n  superseded or obsolete, or already covered by the global store (note\n  \"covered globally\" in the reason).\n- \"keep\" \u2014 still actively useful to this session, or genuinely uncertain.\n\nRules:\n- When an entry is marked \"covered globally\" in the listing, prefer \"archive\"\n  or \"keep\" over \"promote\" \u2014 promoting a duplicate gains nothing.\n- Do not promote local task state, work-in-progress notes, or content tied to\n  one session's ephemeral details.\n- Skills: only \"promote\" a skill entry that is a genuinely reusable procedure\n  meeting the DSH skill quality standard; one-off workflows are \"archive\" or\n  \"keep\".\n- SPLIT PROMOTION: when an entry mixes a stable, cross-session-reusable part\n  WITH session-specific snapshot details, do NOT promote it whole. Instead\n  give verdict \"archive\" WITH a \"promote\" sub-object holding a CLEANED\n  version of only the durable part (a stable title + the persistent facts,\n  stripped of dates/states/one-off figures). Ephemeral snapshot content stays\n  out of the sub-object \u2014 it is left behind in the archive. A sub-object is\n  only meaningful on \"archive\" verdicts.\n\nReturn JSON only:\n{\n  \"rationale\": \"one or two sentences\",\n  \"items\": [\n    {\"key\": \"memory:foo\", \"verdict\": \"promote|archive|keep\", \"reason\": \"why\"},\n    {\"key\": \"memory:bar\", \"verdict\": \"archive\", \"reason\": \"why\",\n     \"promote\": {\"title\": \"cleaned stable title\", \"content\": \"cleaned durable part only\"}}\n  ]\n}\nOnly keys from the provided list are allowed; any entry you omit defaults to \"keep\".";
+export interface AssessOptions {
+    /** Output token budget for the assessment call. */
+    maxOutputTokens?: number;
+    /** Abort signal forwarded to the model call. */
+    signal?: AbortSignal;
+}
+/**
+ * Ask the model to classify the audited local candidates. Routes through the
+ * calling agent's own provider/model (same model the session runs on), with
+ * reasoning disabled so the output budget goes to the JSON verdicts.
+ */
+export declare function assessLocalEntries(ctx: Context, agent: Agent, candidates: readonly WrapupCandidate[], options?: AssessOptions): Promise<WrapupAssessment>;
+//# sourceMappingURL=wrapup.d.ts.map