dsh-continual-evolve 0.7.1 → 0.7.3

package/lib/index.js

@@ -3,9 +3,10 @@
  *
  * Mounts the evolution engine, registers the model-facing evolve_* tools,
  * the human-facing /evolve command, the system-prompt guidance section, and
- * (opt-in) the automatic review gate that runs the planner on a turn
- * interval. Store roots default under the resolved DSH home; a deployment
- * may override `baseDir` in the plugin config.
+ * the automatic memory+review pipeline. The listener is always registered,
+ * while its effective state is controlled by the runtime switch. Successful
+ * turns feed a dedicated memory agent and general review through one
+ * per-session serial scheduler.
  */
 import { join } from "node:path";
 import z from "@deepseek-ai/schemastery";
@@ -29,9 +30,9 @@ export const Config = z.object({
     baseDir: z.string(),
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z.natural().default(118),
-    /** Enable the automatic review gate (off by default: it costs model calls). */
+    /** Initial automatic-review default when no runtime switch exists (off by default: it costs model calls). */
     autoReview: z.boolean().default(false),
-    /** Gate runs when this many turns have passed since the last review. */
+    /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z.natural().default(6),
     /** Trajectory slice handed to the gate, in characters. */
     maxReviewInputChars: z.natural().default(40000),
@@ -177,25 +178,29 @@ export function apply(ctx, config) {
     void restoreMounted(ctx, baseDir).catch((cause) => {
         ctx.logger("continual-evolve").warn(`mount restore failed: ${cause instanceof Error ? cause.message : String(cause)}`);
     });
-    if (config.autoReview) {
-        registerAutoReview(ctx, engine, {
-            intervalTurns: config.reviewIntervalTurns ?? 6,
-            maxInputChars: config.maxReviewInputChars ?? 40000,
-            budgetTokens: config.reviewBudgetTokens ?? 4096,
-            notifyOnAutoReview: config.notifyOnAutoReview ?? true,
-            localFate: config.localFate ?? true,
-            fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
-            goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
-            promotionPolicy,
-            autoCase: config.autoCase ?? true,
-            rubricKey,
-            ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
-            ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
-            ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
-            ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
-        });
-        ctx.logger("continual-evolve").info(`continual-evolve auto-review enabled (every ${config.reviewIntervalTurns ?? 6} turns; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);
-    }
+    // The listener is always registered. `autoReview` is only the initial
+    // runtime default; `/evolve resume` can enable it without a profile edit
+    // or process restart, while manual tools and commands stay independent.
+    registerAutoReview(ctx, engine, {
+        intervalTurns: config.reviewIntervalTurns ?? 6,
+        enabledByDefault: config.autoReview ?? false,
+        maxInputChars: config.maxReviewInputChars ?? 40000,
+        budgetTokens: config.reviewBudgetTokens ?? 4096,
+        notifyOnAutoReview: config.notifyOnAutoReview ?? true,
+        localFate: config.localFate ?? true,
+        fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
+        goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+        promotionPolicy,
+        autoCase: config.autoCase ?? true,
+        rubricKey,
+        ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
+        ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
+        requireGlobalApproval: config.requireGlobalApproval ?? true,
+        ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
+        ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
+    });
+    const runtimeDefault = config.autoReview ?? false;
+    ctx.logger("continual-evolve").info(`continual-evolve auto-review registered (default ${runtimeDefault ? "on" : "off"}; successful-turn memory agent + general review; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);
     ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
 }
 //# sourceMappingURL=index.js.map

package/lib/llm-text.d.ts

@@ -9,13 +9,15 @@
  * and JSON parsing.
  */
 import type { Context } from "@deepseek-ai/cordis";
-import { type Message, type TokenUsage } from "@deepseek-ai/dsh-llm";
+import { type ContentBlock, type LlmResolvedModelInfo, type Message, type ReasoningEffortId, type RequestMessage, type TokenUsage, type ToolSchema } from "@deepseek-ai/dsh-llm";
 /** Terminal outcome of one shared direct LLM call. */
 export type StreamTextOutcome = "success" | "max-tokens" | "error" | "aborted" | "empty";
 /** Provider usage and terminal result observed after the stream settles. */
 export interface StreamTextObservation {
     usage?: TokenUsage;
     outcome: StreamTextOutcome;
+    /** Exact capability-derived effort used for this call; absent when no metadata was exposed. */
+    reasoningEffort?: ReasoningEffortId;
 }
 /** Diagnostic observer invoked before streamText returns or throws. */
 export type StreamTextUsageObserver = (observation: StreamTextObservation) => void;
@@ -40,14 +42,55 @@ export interface StreamTextOptions {
      */
     onUsage?: StreamTextUsageObserver;
 }
+/** One provider request for a bounded internal agent/tool loop. */
+export interface StreamModelTurnOptions {
+    provider: string;
+    model: string;
+    messages: readonly RequestMessage[];
+    /** One-shot system slot. Omit when messages already carry the system prompt. */
+    system?: string;
+    /** Closed tool schemas for this request; omitted means no tools. */
+    tools?: readonly ToolSchema[];
+    maxTokens?: number;
+    signal?: AbortSignal | undefined;
+    /** Require at least one text block; tool-only turns must leave this false. */
+    requireText?: boolean;
+    /** Require visible text or a tool call; reasoning-only agent turns are empty. */
+    requireTextOrToolCall?: boolean;
+    /** Same diagnostic observer contract as {@link StreamTextOptions.onUsage}. */
+    onUsage?: StreamTextUsageObserver;
+}
 /**
- * Stream a single-turn text completion through `ctx.llm`. Forces
- * `reasoningEffort: off` so the model spends its budget on the answer,
- * not visible thinking (reasoning models otherwise produce zero text
- * blocks — the exact failure recorded in FAQ #7).
+ * Select the lowest reasoning effort an exact model advertises.
+ *
+ * An enabled effort wins over a declared closing effort. The adapter-preferred
+ * first enabled effort is the lowest enabled level it exposes; a closing effort
+ * is only a fallback when the model publishes no enabled level. No capability
+ * list means no caller-supplied effort.
+ *
+ * @param modelInfo - exact resolved-model metadata, when the provider exposes it.
+ * @returns The selected provider-owned effort id, or `undefined` when unknown.
+ */
+export declare function selectLowestReasoningEffort(modelInfo: Pick<LlmResolvedModelInfo, "reasoning"> | undefined): ReasoningEffortId | undefined;
+/**
+ * Stream a single-turn text completion through `ctx.llm`. The request uses the
+ * exact provider/model's lowest advertised reasoning effort, omitting the field
+ * when the model exposes no reasoning metadata.
  *
  * @returns The concatenated text blocks from the response.
  * @throws On provider error, abort, max-token truncation, or empty output.
  */
+/**
+ * Stream one provider/model turn and return its assembled content blocks.
+ * This is the shared primitive for text callers and bounded tool loops; finish
+ * state, capability-derived effort, cancellation, and usage observation stay
+ * inside this boundary.
+ *
+ * @param ctx - DSH context providing the LLM runtime.
+ * @param opts - Exact route, messages, optional tools, and output requirements.
+ * @returns The assembled content blocks; caller decides how to interpret them.
+ * @throws On provider error, abort, max-token truncation, or capability lookup failure.
+ */
+export declare function streamModelTurn(ctx: Context, opts: StreamModelTurnOptions): Promise<ContentBlock[]>;
 export declare function streamText(ctx: Context, opts: StreamTextOptions): Promise<string>;
 //# sourceMappingURL=llm-text.d.ts.map

package/lib/llm-text.js

@@ -1,30 +1,71 @@
-import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { BlockAssembler, createUserMessage, } from "@deepseek-ai/dsh-llm";
 import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
+const CLOSED_REASONING_EFFORTS = new Set(["disabled", "off", "none"]);
 /**
- * Stream a single-turn text completion through `ctx.llm`. Forces
- * `reasoningEffort: off` so the model spends its budget on the answer,
- * not visible thinking (reasoning models otherwise produce zero text
- * blocks — the exact failure recorded in FAQ #7).
+ * Select the lowest reasoning effort an exact model advertises.
+ *
+ * An enabled effort wins over a declared closing effort. The adapter-preferred
+ * first enabled effort is the lowest enabled level it exposes; a closing effort
+ * is only a fallback when the model publishes no enabled level. No capability
+ * list means no caller-supplied effort.
+ *
+ * @param modelInfo - exact resolved-model metadata, when the provider exposes it.
+ * @returns The selected provider-owned effort id, or `undefined` when unknown.
+ */
+export function selectLowestReasoningEffort(modelInfo) {
+    const efforts = modelInfo?.reasoning?.efforts;
+    if (efforts !== undefined && !Array.isArray(efforts)) {
+        throw new Error("evolve: invalid model reasoning metadata");
+    }
+    if (!efforts || efforts.length === 0)
+        return undefined;
+    for (const effort of efforts) {
+        if (typeof effort?.id !== "string") {
+            throw new Error("evolve: invalid model reasoning metadata");
+        }
+    }
+    return efforts.find((effort) => !CLOSED_REASONING_EFFORTS.has(effort.id))?.id ?? efforts[0]?.id;
+}
+async function resolveReasoningEffort(ctx, opts) {
+    // The current DSH host exposes this method. Keep a capability-less test or
+    // older host usable by treating the absent query as unknown metadata.
+    if (typeof ctx.llm.resolveModelInfo !== "function")
+        return undefined;
+    const modelInfo = await ctx.llm.resolveModelInfo(opts.provider, opts.model);
+    return selectLowestReasoningEffort(modelInfo);
+}
+/**
+ * Stream a single-turn text completion through `ctx.llm`. The request uses the
+ * exact provider/model's lowest advertised reasoning effort, omitting the field
+ * when the model exposes no reasoning metadata.
  *
  * @returns The concatenated text blocks from the response.
  * @throws On provider error, abort, max-token truncation, or empty output.
  */
-export async function streamText(ctx, opts) {
+/**
+ * Stream one provider/model turn and return its assembled content blocks.
+ * This is the shared primitive for text callers and bounded tool loops; finish
+ * state, capability-derived effort, cancellation, and usage observation stay
+ * inside this boundary.
+ *
+ * @param ctx - DSH context providing the LLM runtime.
+ * @param opts - Exact route, messages, optional tools, and output requirements.
+ * @returns The assembled content blocks; caller decides how to interpret them.
+ * @throws On provider error, abort, max-token truncation, or capability lookup failure.
+ */
+export async function streamModelTurn(ctx, opts) {
     const assembler = new BlockAssembler();
     let outcome = "error";
+    let reasoningEffort;
     try {
+        reasoningEffort = await resolveReasoningEffort(ctx, opts);
         for await (const chunk of ctx.llm.stream({
             provider: opts.provider,
             model: opts.model,
-            system: opts.system,
-            messages: [
-                ...(opts.prefixMessages ?? []),
-                createUserMessage({
-                    content: [{ type: "text", text: opts.prompt }],
-                    source: EVOLVE_MESSAGE_SOURCE,
-                }),
-            ],
-            reasoningEffort: ReasoningEffortId("off"),
+            messages: [...opts.messages],
+            ...(opts.system === undefined ? {} : { system: opts.system }),
+            ...(opts.tools === undefined ? {} : { tools: [...opts.tools] }),
+            ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
             maxTokens: opts.maxTokens ?? 8000,
             ...(opts.signal ? { signal: opts.signal } : {}),
         })) {
@@ -43,25 +84,51 @@ export async function streamText(ctx, opts) {
             outcome = "max-tokens";
             throw new Error("evolve: LLM output budget exhausted (max-tokens)");
         }
-        const text = assembler
-            .blocks()
-            .filter((block) => block.type === "text")
-            .map((block) => block.text)
-            .join("\n");
-        if (text.length === 0) {
-            outcome = "empty";
-            throw new Error("evolve: LLM produced no text output");
-        }
-        outcome = "success";
-        return text;
+        const blocks = assembler.blocks();
+        const hasText = blocks.some((block) => block.type === "text" && block.text.length > 0);
+        const hasToolCall = blocks.some((block) => block.type === "tool-call");
+        const missingRequiredOutput = (opts.requireText === true && !hasText)
+            || (opts.requireTextOrToolCall === true && !hasText && !hasToolCall);
+        outcome = blocks.length === 0 || missingRequiredOutput ? "empty" : "success";
+        return blocks;
     }
     finally {
         try {
-            opts.onUsage?.({ ...(assembler.usage ? { usage: assembler.usage } : {}), outcome });
+            opts.onUsage?.({
+                ...(assembler.usage ? { usage: assembler.usage } : {}),
+                outcome,
+                ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+            });
         }
         catch {
             // Usage observation is diagnostic; its failure must not alter the model call.
         }
     }
 }
+export async function streamText(ctx, opts) {
+    const blocks = await streamModelTurn(ctx, {
+        provider: opts.provider,
+        model: opts.model,
+        system: opts.system,
+        messages: [
+            ...(opts.prefixMessages ?? []),
+            createUserMessage({
+                content: [{ type: "text", text: opts.prompt }],
+                source: EVOLVE_MESSAGE_SOURCE,
+            }),
+        ],
+        requireText: true,
+        ...(opts.maxTokens === undefined ? {} : { maxTokens: opts.maxTokens }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.onUsage ? { onUsage: opts.onUsage } : {}),
+    });
+    const text = blocks
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (text.length === 0) {
+        throw new Error("evolve: LLM produced no text output");
+    }
+    return text;
+}
 //# sourceMappingURL=llm-text.js.map

package/lib/memory-agent.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Dedicated background memory extraction agent.
+ *
+ * This is the DSH counterpart of ZCode's project-memory agent loop. It keeps
+ * an independent request history, exposes only a frozen memory manifest and a
+ * structured proposal tool, and never writes state itself. Every accepted edit
+ * is handed to EvolutionEngine so scope approval, snapshots, versioning,
+ * rollback, and audit remain mandatory.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { type ToolSchema } from "@deepseek-ai/dsh-llm";
+import { type ScopeApprovalDecision } from "./approval.js";
+import { type PrefixCacheOptions } from "./prefix-cache.js";
+import { type EvolutionEngine } from "./service.js";
+import { type TokenUsageTarget } from "./token-usage.js";
+import type { EntrySource, HarnessEntry, HarnessScope, HarnessState, RefinementEdit, RefinementProposal, RefinementResult } from "./types.js";
+/** ZCode parity: the extractor may inspect memory and propose at most five times. */
+export declare const MEMORY_AGENT_MAX_TURNS = 5;
+/** Bound one proposal so approval text and engine compensation stay reviewable. */
+export declare const MEMORY_AGENT_MAX_EDITS = 20;
+/** The complete tool-name allowlist exposed by the memory agent. */
+export declare const MEMORY_AGENT_TOOL_NAMES: readonly ["memory_search", "memory_propose"];
+export type MemoryAgentToolName = (typeof MEMORY_AGENT_TOOL_NAMES)[number];
+/** One frozen memory entry visible to the extractor for the whole run. */
+export type MemoryManifestEntry = HarnessEntry;
+/** A memory-only edit with an explicit persistence target. */
+export type ScopedMemoryEdit = RefinementEdit & {
+    kind: "memory";
+    targetScope: HarnessScope;
+};
+/** Structured result returned by `memory_propose`. */
+export interface MemoryExtractionProposal extends Omit<RefinementProposal, "edits"> {
+    edits: ScopedMemoryEdit[];
+}
+/** Baseline states captured before the first extractor model turn. */
+export interface MemoryScopeBaselines {
+    local: HarnessState;
+    project?: HarnessState;
+    global: HarnessState;
+}
+/** Result of one bounded extractor loop. */
+export interface MemoryAgentRun {
+    proposal: MemoryExtractionProposal;
+    turns: number;
+    searches: number;
+}
+/** Scoped results after the proposal crosses the governed engine boundary. */
+export interface MemoryApplicationResult {
+    results: RefinementResult[];
+    declinedScopes: HarnessScope[];
+}
+/** Provider-facing schemas for the closed memory-only tool set. */
+export declare const MEMORY_AGENT_TOOL_SCHEMAS: readonly ToolSchema[];
+/** Instructions for the dedicated loop; model text is always untrusted. */
+export declare const MEMORY_AGENT_SYSTEM_PROMPT = "You are the dedicated background memory extraction agent for a continual-evolution harness.\n\nYou receive only an incremental conversation checkpoint and a frozen manifest of existing memory entries. Your entire job is to decide whether this checkpoint contains a durable fact worth remembering. Never propose prompt notes, skills, subagent specs, code changes, or general conversation summaries.\n\nRules:\n- Use memory_search before creating when the manifest may already cover the topic. Update an existing entry instead of creating a near-duplicate.\n- Every memory entry contains exactly one fact. Classify it with metadata.memoryType = user | feedback | project | reference.\n- feedback and project memories must state the fact, Why it matters, and How to apply it next time.\n- Never invent a user preference. Ground every proposal in the supplied conversation evidence and existing memory.\n- Every edit must have kind=memory, an explicit targetScope, and a coherent blastRadius.\n- targetScope=local is session staging. project persists within the current repository. global persists across projects. project/global require human approval before application.\n- update/delete/archive must name an existing id from the same targetScope. Prefer archive over delete when the fact is obsolete but should remain restorable.\n- You cannot read or write source files, call agents, use MCP, use the network, or mutate the harness directly. memory_propose is the only finish tool and never writes state itself.\n- If no durable memory is justified, call memory_propose with edits=[].\n- Always finish by calling memory_propose. Do not return unproposed prose.";
+/** Build the frozen memory manifest from a merged harness view. */
+export declare function buildMemoryManifest(state: HarnessState): MemoryManifestEntry[];
+/** Render a bounded manifest index; full bodies remain available through memory_search. */
+export declare function formatMemoryManifest(entries: readonly MemoryManifestEntry[], maxChars?: number): string;
+/** Rank frozen manifest entries with CJK-aware token overlap and stable tie-breaking. */
+export declare function searchMemoryManifest(entries: readonly MemoryManifestEntry[], query: string, maxResults?: number): MemoryManifestEntry[];
+/** Inputs for one bounded background memory extraction loop. */
+export interface MemoryAgentOptions {
+    provider: string;
+    model: string;
+    manifest: readonly MemoryManifestEntry[];
+    trajectory: string;
+    trajectoryEvents?: readonly unknown[];
+    prefixCache?: PrefixCacheOptions;
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+    tokenUsage?: TokenUsageTarget;
+}
+/**
+ * Run the dedicated loop against a frozen manifest.
+ *
+ * @throws On provider failure, abort, malformed tool arguments, policy denial,
+ * a non-memory proposal, or exhaustion of the bounded internal turn budget.
+ */
+export declare function runMemoryAgent(ctx: Context, options: MemoryAgentOptions): Promise<MemoryAgentRun>;
+/** Strictly parse and policy-check the structured `memory_propose` payload. */
+export declare function parseMemoryExtractionProposal(value: unknown, manifest: readonly MemoryManifestEntry[]): MemoryExtractionProposal;
+export interface ApplyMemoryProposalOptions {
+    agent: Agent;
+    baselines: MemoryScopeBaselines;
+    projectKey?: string;
+    requireApproval: boolean;
+    source?: EntrySource;
+    signal?: AbortSignal;
+    /** Outer cursor used to scope reusable approval decisions. */
+    decisionCursor?: string;
+    /** Prior decisions for the same cursor and exact scoped proposal. */
+    scopeDecisions?: Readonly<Record<string, ScopeApprovalDecision>>;
+    /** Persist each decision before a later scope can fail. */
+    onScopeDecision?: (key: string, decision: ScopeApprovalDecision) => void;
+}
+/**
+ * Render the authoritative persistent-scope diff shown to the human. Model
+ * prose is retained only as an explicitly untrusted summary; actions, targets,
+ * content previews, memory types, and conflict warnings come from code.
+ */
+export declare function renderMemoryApprovalDetails(proposal: MemoryExtractionProposal, scope: "project" | "global", state: HarnessState, maxChars?: number): string;
+/**
+ * Apply one accepted proposal through the only mutation engine. All persistent
+ * approvals are resolved before the first write, so an unavailable approval
+ * boundary cannot leave a partially applied batch. Explicit rejection is a
+ * no-op for that scope; service/question failures remain retryable errors.
+ */
+export declare function applyMemoryExtractionProposal(ctx: Context, engine: EvolutionEngine, proposal: MemoryExtractionProposal, options: ApplyMemoryProposalOptions): Promise<MemoryApplicationResult>;
+//# sourceMappingURL=memory-agent.d.ts.map