dsh-continual-evolve 0.1.0

package/lib/evaluate.js

@@ -0,0 +1,142 @@
+import { mapPool } from "./pool.js";
+import { decryptRubric, deriveKey, DEV_RUBRIC_KEY } from "./rubric.js";
+/** Key used when the caller did not resolve one: mirrors resolveRubricKey's last-resort dev fallback. */
+function devRubricKey() {
+    return deriveKey(DEV_RUBRIC_KEY);
+}
+const EVAL_SYSTEM_PROMPT = `You are one evaluation unit in a benchmark matrix.
+
+You are the agent under evaluation. Perform the case task using your tools,
+then score your own execution strictly against the rubric. The harness
+guidance attached to the state under test is included in the task.
+
+Your reply is structured (see the requested output schema): caseId, run,
+score (0-100), passed (true iff score >= the stated threshold), and notes
+(concrete evidence for the score).`;
+const CELL_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        caseId: { type: "string" },
+        run: { type: "number" },
+        score: { type: "number" },
+        passed: { type: "boolean" },
+        notes: { type: "string" },
+    },
+    required: ["caseId", "run", "score", "passed", "notes"],
+};
+/** How many evaluation units may run concurrently (bounded subagent fan-out). */
+export const DEFAULT_EVALUATION_CONCURRENCY = 4;
+export async function evaluateState(ctx, agent, options) {
+    if (!agent.options.provider || !agent.options.model) {
+        throw new Error("evolve: benchmark evaluation requires a provider/model route");
+    }
+    const subagents = ctx.subagents;
+    if (!subagents) {
+        throw new Error("evolve: benchmark evaluation requires the subagents service");
+    }
+    const units = [];
+    for (const c of options.cases) {
+        for (let run = 1; run <= options.runs; run += 1) {
+            units.push({ case: c, run });
+        }
+    }
+    const cells = await mapPool(units, DEFAULT_EVALUATION_CONCURRENCY, (unit) => runUnit(subagents, agent, options, unit.case, unit.run));
+    return { label: options.label, cells, stopReason: "completed" };
+}
+async function runUnit(subagents, agent, options, c, run) {
+    // The ONLY rubric decryption point: the envelope is opened here, in the
+    // host, and the plaintext goes straight into the child prompt. The
+    // optimizer never reaches this path.
+    let rubric;
+    try {
+        rubric = decryptRubric(c.rubric, options.rubricKey ?? devRubricKey());
+    }
+    catch (cause) {
+        return {
+            caseId: c.id,
+            run,
+            score: 0,
+            passed: false,
+            notes: `rubric decrypt failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const prompt = [
+        EVAL_SYSTEM_PROMPT,
+        "---",
+        "Your harness guidance (state under test):",
+        `<harness_overview>\n${options.harnessOverview}\n</harness_overview>`,
+        `Case ${c.id} — task (statement):\n${c.statement}`,
+        `Rubric — score yourself strictly against these criteria:\n${rubric}`,
+        `Run ${run} of ${options.runs}. passThreshold = ${options.passThreshold}.`,
+        "Execute the task with your tools, then produce the structured evaluation.",
+    ].join("\n\n");
+    try {
+        const runObj = await subagents.start("spawn", {
+            label: `${c.id} r${run}`,
+            prompt: [{ type: "text", text: prompt }],
+            parent: agent,
+            signal: options.signal ?? new AbortController().signal,
+            outputSchema: CELL_SCHEMA,
+        });
+        try {
+            const settled = await runObj.result;
+            if (settled.stopReason !== "completed") {
+                throw new Error(`child stopped: ${settled.stopReason ?? "unknown"}`);
+            }
+            const parsed = normalizeCell(settled.structured, c.id, run, options.passThreshold) ??
+                fromOutputText(settled.output, c.id, run, options.passThreshold);
+            if (!parsed) {
+                throw new Error("child returned neither a structured value nor usable text");
+            }
+            return parsed;
+        }
+        finally {
+            runObj.dispose();
+        }
+    }
+    catch (cause) {
+        return {
+            caseId: c.id,
+            run,
+            score: 0,
+            passed: false,
+            notes: `unit failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+}
+/** Validate a provider-validated structured cell; returns undefined when malformed. */
+export function normalizeCell(value, caseId, run, passThreshold) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const score = Number(record["score"]);
+    if (!Number.isFinite(score))
+        return undefined;
+    return {
+        caseId: typeof record["caseId"] === "string" && record["caseId"].length > 0 ? record["caseId"] : caseId,
+        run: typeof record["run"] === "number" && Number.isFinite(record["run"]) ? Math.trunc(record["run"]) : run,
+        score: Math.min(100, Math.max(0, score)),
+        passed: record["passed"] === true || score >= passThreshold,
+        notes: typeof record["notes"] === "string" ? record["notes"] : "",
+    };
+}
+/** Fallback: recover a cell from the child's text blocks when no structured value arrived. */
+function fromOutputText(blocks, caseId, run, passThreshold) {
+    if (!Array.isArray(blocks))
+        return undefined;
+    const text = blocks
+        .filter((block) => block.type === "text")
+        .map((block) => block.text ?? "")
+        .join("\n");
+    if (text.length === 0)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return normalizeCell(value, caseId, run, passThreshold);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=evaluate.js.map

package/lib/goal.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Goal-driven evolution rounds (v3 optional item, design.md §6): a
+ * same-session goal turns the auto-review into a per-round driver — while a
+ * goal is active, the review gate runs every round instead of every
+ * `reviewIntervalTurns`, so the "continual evolution loop" is driven by the
+ * goal's round machine (goal-round-driver keeps the session continuing) and
+ * stops when the goal is completed or blocked.
+ *
+ * The goal service (`ctx.goals`) is resolved lazily and never required
+ * (FAQ #1 discipline): without it, `/evolve goal` reports the feature
+ * unavailable and auto-review keeps its plain interval.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+/** The durable goal phases we drive on. */
+export type GoalPhase = "active" | "paused" | "blocked" | "complete";
+/** Minimal structural view of a goal view (duck-typed against dsh-goal). */
+export interface GoalViewLike {
+    readonly id: string;
+    readonly revision: number;
+    readonly objective: string;
+    readonly phase: GoalPhase;
+    readonly maxGoalRounds: number;
+}
+export interface GoalRefLike {
+    readonly id: string;
+    readonly revision: number;
+}
+export interface GoalServiceLike {
+    get(agent: Agent): GoalViewLike | undefined;
+    create(agent: Agent, request: {
+        objective: string;
+        maxGoalRounds?: number;
+    }): GoalViewLike;
+    edit(agent: Agent, ref: GoalRefLike, request: {
+        objective?: string;
+        maxGoalRounds?: number;
+    }): GoalViewLike;
+    complete(agent: Agent, ref: GoalRefLike): GoalViewLike;
+    block?(agent: Agent, ref: GoalRefLike, reason: {
+        code: string;
+        reason: string;
+    }): GoalViewLike;
+}
+/** The default objective used by `/evolve goal` without an explicit one. */
+export declare const DEFAULT_EVOLVE_GOAL_OBJECTIVE = "\u6301\u7EED\u8FDB\u5316\u672C\u4F1A\u8BDD harness \u72B6\u6001\uFF1A\u6BCF\u8F6E\u6C89\u6DC0\u53EF\u590D\u7528\u7ECF\u9A8C\uFF08\u5931\u8D25/\u6218\u672F/\u4E8B\u5B9E/\u59D4\u6D3E\u89C4\u683C\uFF09\uFF0C\u4FDD\u6301\u6761\u76EE\u5C0F\u800C\u5E26\u8BC1\u636E";
+/**
+ * Resolve the goal service lazily; undefined when the profile lacks it.
+ * Uses `ctx.get("goals")` (the global service registry) — a direct property
+ * access like `ctx.goals` walks only the caller's fiber ancestor chain and
+ * throws "cannot get property \"goals\" without inject" for services
+ * provided by sibling plugin entries (the goal plugin is a sibling of this
+ * one in the profile tree).
+ */
+export declare function goalServiceOf(ctx: Context): GoalServiceLike | undefined;
+/** True when a goal view exists and is in a round-driving phase (active). */
+export declare function goalDrivesRounds(view: GoalViewLike | undefined): boolean;
+/** True when a goal exists at all (any phase) — used to gate create vs edit. */
+export declare function goalExists(view: GoalViewLike | undefined): view is GoalViewLike;
+/** Human-readable one-line status for a goal view. */
+export declare function goalStatusText(view: GoalViewLike): string;
+/**
+ * Create or edit the session's evolution goal. With no current goal: create.
+ * With a current goal: edit its objective (create-on-first-use semantics are
+ * enforced by the goal service itself; completed goals may be replaced).
+ */
+export declare function upsertEvolutionGoal(ctx: Context, agent: Agent, objective?: string): GoalViewLike;
+/** Complete the current goal, returning the completed view or undefined. */
+export declare function completeEvolutionGoal(ctx: Context, agent: Agent): GoalViewLike | undefined;
+/** Block the current goal with a reason (when the service supports it). */
+export declare function blockEvolutionGoal(ctx: Context, agent: Agent, reason: string): GoalViewLike | undefined;
+//# sourceMappingURL=goal.d.ts.map

package/lib/goal.js

@@ -0,0 +1,72 @@
+/** The default objective used by `/evolve goal` without an explicit one. */
+export const DEFAULT_EVOLVE_GOAL_OBJECTIVE = "持续进化本会话 harness 状态：每轮沉淀可复用经验（失败/战术/事实/委派规格），保持条目小而带证据";
+/**
+ * Resolve the goal service lazily; undefined when the profile lacks it.
+ * Uses `ctx.get("goals")` (the global service registry) — a direct property
+ * access like `ctx.goals` walks only the caller's fiber ancestor chain and
+ * throws "cannot get property \"goals\" without inject" for services
+ * provided by sibling plugin entries (the goal plugin is a sibling of this
+ * one in the profile tree).
+ */
+export function goalServiceOf(ctx) {
+    return ctx.get("goals");
+}
+/** True when a goal view exists and is in a round-driving phase (active). */
+export function goalDrivesRounds(view) {
+    return view?.phase === "active";
+}
+/** True when a goal exists at all (any phase) — used to gate create vs edit. */
+export function goalExists(view) {
+    return view !== undefined;
+}
+/** Human-readable one-line status for a goal view. */
+export function goalStatusText(view) {
+    const rounds = typeof view.roundsStarted === "number"
+        ? String(view.roundsStarted)
+        : "?";
+    return `[${view.phase}] ${view.objective} (rounds=${rounds}/${view.maxGoalRounds}, revision=${view.revision})`;
+}
+/**
+ * Create or edit the session's evolution goal. With no current goal: create.
+ * With a current goal: edit its objective (create-on-first-use semantics are
+ * enforced by the goal service itself; completed goals may be replaced).
+ */
+export function upsertEvolutionGoal(ctx, agent, objective) {
+    const goals = goalServiceOf(ctx);
+    if (!goals) {
+        throw new Error("evolve: /evolve goal requires the goals service (load @deepseek-ai/dsh-goal)");
+    }
+    const current = goals.get(agent);
+    const nextObjective = objective && objective.length > 0 ? objective : DEFAULT_EVOLVE_GOAL_OBJECTIVE;
+    if (goalExists(current)) {
+        if (current.phase === "active" || current.phase === "paused") {
+            return goals.edit(agent, { id: current.id, revision: current.revision }, { objective: nextObjective });
+        }
+    }
+    return goals.create(agent, { objective: nextObjective });
+}
+/** Complete the current goal, returning the completed view or undefined. */
+export function completeEvolutionGoal(ctx, agent) {
+    const goals = goalServiceOf(ctx);
+    if (!goals) {
+        throw new Error("evolve: /evolve goal requires the goals service (load @deepseek-ai/dsh-goal)");
+    }
+    const current = goals.get(agent);
+    if (!goalExists(current) || current.phase === "complete") {
+        return current;
+    }
+    return goals.complete(agent, { id: current.id, revision: current.revision });
+}
+/** Block the current goal with a reason (when the service supports it). */
+export function blockEvolutionGoal(ctx, agent, reason) {
+    const goals = goalServiceOf(ctx);
+    if (!goals || typeof goals.block !== "function") {
+        return undefined;
+    }
+    const current = goals.get(agent);
+    if (!goalExists(current) || current.phase !== "active") {
+        return current;
+    }
+    return goals.block(agent, { id: current.id, revision: current.revision }, { code: "evolve-blocked", reason });
+}
+//# sourceMappingURL=goal.js.map

package/lib/index.d.ts

@@ -0,0 +1,93 @@
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+import { type EvolutionEngine } from "./service.js";
+export declare const name = "continual-evolve";
+/** Service key under which the evolution engine is published. */
+export declare const EVOLUTION_SERVICE = "evolution";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    /** Root for evolution stores; defaults to the resolved DSH home. */
+    baseDir: z<string, string>;
+    /** System-prompt section order for the evolution guidance. */
+    sectionOrder: z<number, number>;
+    /** Enable the automatic review gate (off by default: it costs model calls). */
+    autoReview: z<boolean, boolean>;
+    /** Gate runs when this many turns have passed since the last review. */
+    reviewIntervalTurns: z<number, number>;
+    /** Trajectory slice handed to the gate, in characters. */
+    maxReviewInputChars: z<number, number>;
+    /** Output budget for the cheap gate call. */
+    reviewBudgetTokens: z<number, number>;
+    /** After an approved gate run with applied edits, queue a visible follow-up notice. */
+    notifyOnAutoReview: z<boolean, boolean>;
+    /** Cross-session (global) edits require an explicit human approval. */
+    requireGlobalApproval: z<boolean, boolean>;
+    /** Skills root for materialized skill entries; defaults to <dshHome>/skills. */
+    skillsDir: z<string, string>;
+    /** Passphrase for rubric encryption; falls back to DSH_EVOLVE_RUBRIC_KEY, then a local key file. */
+    rubricKey: z<string, string>;
+    /** Write all cordis log messages to <baseDir>/evolve/plugin.log (JSONL). */
+    logToFile: z<boolean, boolean>;
+    /** File log level: 0=error, 1=info, 2=warn, 3=debug. */
+    logLevel: z<number, number>;
+    /** Rotate the file log when it exceeds this many bytes. */
+    logMaxBytes: z<number, number>;
+    /** After a benchmark decision rejects a candidate, roll the refinement back automatically. */
+    autoRollbackOnReject: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    /** Root for evolution stores; defaults to the resolved DSH home. */
+    baseDir: z<string, string>;
+    /** System-prompt section order for the evolution guidance. */
+    sectionOrder: z<number, number>;
+    /** Enable the automatic review gate (off by default: it costs model calls). */
+    autoReview: z<boolean, boolean>;
+    /** Gate runs when this many turns have passed since the last review. */
+    reviewIntervalTurns: z<number, number>;
+    /** Trajectory slice handed to the gate, in characters. */
+    maxReviewInputChars: z<number, number>;
+    /** Output budget for the cheap gate call. */
+    reviewBudgetTokens: z<number, number>;
+    /** After an approved gate run with applied edits, queue a visible follow-up notice. */
+    notifyOnAutoReview: z<boolean, boolean>;
+    /** Cross-session (global) edits require an explicit human approval. */
+    requireGlobalApproval: z<boolean, boolean>;
+    /** Skills root for materialized skill entries; defaults to <dshHome>/skills. */
+    skillsDir: z<string, string>;
+    /** Passphrase for rubric encryption; falls back to DSH_EVOLVE_RUBRIC_KEY, then a local key file. */
+    rubricKey: z<string, string>;
+    /** Write all cordis log messages to <baseDir>/evolve/plugin.log (JSONL). */
+    logToFile: z<boolean, boolean>;
+    /** File log level: 0=error, 1=info, 2=warn, 3=debug. */
+    logLevel: z<number, number>;
+    /** Rotate the file log when it exceeds this many bytes. */
+    logMaxBytes: z<number, number>;
+    /** After a benchmark decision rejects a candidate, roll the refinement back automatically. */
+    autoRollbackOnReject: z<boolean, boolean>;
+}>>;
+/** Structurally typed resolved config (loader passes the validated object). */
+export interface EvolveConfig {
+    baseDir?: string;
+    sectionOrder?: number;
+    autoReview?: boolean;
+    reviewIntervalTurns?: number;
+    maxReviewInputChars?: number;
+    reviewBudgetTokens?: number;
+    notifyOnAutoReview?: boolean;
+    requireGlobalApproval?: boolean;
+    skillsDir?: string;
+    rubricKey?: string;
+    /** Write all cordis log messages to <baseDir>/evolve/plugin.log (JSONL). */
+    logToFile?: boolean;
+    /** File log level: 0=error, 1=info, 2=warn, 3=debug. */
+    logLevel?: number;
+    /** Rotate the file log when it exceeds this many bytes. */
+    logMaxBytes?: number;
+    /** After a benchmark decision rejects a candidate, roll the refinement back automatically. */
+    autoRollbackOnReject?: boolean;
+}
+export interface EvolutionService {
+    readonly engine: EvolutionEngine;
+    readonly baseDir: string;
+}
+export declare function apply(ctx: Context, config: EvolveConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,116 @@
+/**
+ * dsh-continual-evolve — plugin entry (Phase 2: auto review gate).
+ *
+ * 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.
+ */
+import { join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { createEvolutionEngine } from "./service.js";
+import { registerEvolveTools } from "./tool.js";
+import { registerEvolveCommand } from "./command.js";
+import { registerAutoReview } from "./auto.js";
+import { syncSkillsFromResult } from "./skill.js";
+import { entriesSectionText } from "./inject.js";
+import { resolveRubricKey } from "./rubric.js";
+import { restoreMounted } from "./mount.js";
+import { registerFileLogger } from "./logfile.js";
+export const name = "continual-evolve";
+/** Service key under which the evolution engine is published. */
+export const EVOLUTION_SERVICE = "evolution";
+export const inject = ["tools", "commands", "systemPrompt", "llm", "sessionQuery", "agents", "userQuestions", "subagents"];
+export const Config = z.object({
+    /** Root for evolution stores; defaults to the resolved DSH home. */
+    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). */
+    autoReview: z.boolean().default(false),
+    /** Gate runs when this many turns have passed since the last review. */
+    reviewIntervalTurns: z.natural().default(6),
+    /** Trajectory slice handed to the gate, in characters. */
+    maxReviewInputChars: z.natural().default(40000),
+    /** Output budget for the cheap gate call. */
+    reviewBudgetTokens: z.natural().default(4096),
+    /** After an approved gate run with applied edits, queue a visible follow-up notice. */
+    notifyOnAutoReview: z.boolean().default(true),
+    /** Cross-session (global) edits require an explicit human approval. */
+    requireGlobalApproval: z.boolean().default(true),
+    /** Skills root for materialized skill entries; defaults to <dshHome>/skills. */
+    skillsDir: z.string(),
+    /** Passphrase for rubric encryption; falls back to DSH_EVOLVE_RUBRIC_KEY, then a local key file. */
+    rubricKey: z.string(),
+    /** Write all cordis log messages to <baseDir>/evolve/plugin.log (JSONL). */
+    logToFile: z.boolean().default(true),
+    /** File log level: 0=error, 1=info, 2=warn, 3=debug. */
+    logLevel: z.natural().default(1),
+    /** Rotate the file log when it exceeds this many bytes. */
+    logMaxBytes: z.natural().default(5 * 1024 * 1024),
+    /** After a benchmark decision rejects a candidate, roll the refinement back automatically. */
+    autoRollbackOnReject: z.boolean().default(true),
+});
+export function apply(ctx, config) {
+    const baseDir = resolveDshHome(config.baseDir);
+    const skillsRoot = config.skillsDir ? expandHomePath(config.skillsDir) : join(baseDir, "skills");
+    const engine = createEvolutionEngine(baseDir, {
+        onApplied: (result) => {
+            try {
+                syncSkillsFromResult(skillsRoot, result);
+            }
+            catch (cause) {
+                ctx
+                    .logger("continual-evolve")
+                    .warn(`skill materialization failed for ${result.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        },
+    });
+    ctx.provide(EVOLUTION_SERVICE, { engine, baseDir });
+    ctx.systemPrompt.section({
+        name: "tool:continual-evolve",
+        order: config.sectionOrder ?? 118,
+        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use global: true only for stable cross-session lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
+    });
+    // Phase 2: make prompt entries real system-prompt content and subagent
+    // entries real delegation specs. The text is a provider evaluated at every
+    // assembly with the assembling agent; a store without prompt/subagent
+    // entries renders to "" and the prompt renderer drops the section.
+    ctx.systemPrompt.section({
+        name: "tool:continual-evolve:entries",
+        order: (config.sectionOrder ?? 118) + 1,
+        text: (context) => entriesSectionText(engine, context.agent),
+    });
+    const gate = { requireGlobalApproval: config.requireGlobalApproval ?? true };
+    registerEvolveTools(ctx, engine, gate);
+    registerEvolveCommand(ctx, engine, gate, {
+        rubricKey: resolveRubricKey(baseDir, config.rubricKey, process.env, (m) => ctx.logger("continual-evolve").warn(m)),
+        autoRollbackOnReject: config.autoRollbackOnReject ?? true,
+    });
+    // Plugin-owned file logging: every cordis log message lands in
+    // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
+    // no extra component to install, no startup-script dependency.
+    if (config.logToFile !== false) {
+        registerFileLogger(ctx, baseDir, {
+            logLevel: config.logLevel ?? 1,
+            ...(config.logMaxBytes !== undefined ? { logMaxBytes: config.logMaxBytes } : {}),
+        });
+    }
+    // v2 optional: restore hot-mounted skill plugins after a restart.
+    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,
+        });
+        ctx.logger("continual-evolve").info(`continual-evolve auto-review enabled (every ${config.reviewIntervalTurns ?? 6} turns)`);
+    }
+    ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
+}
+//# sourceMappingURL=index.js.map

package/lib/inject.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Real prompt/spec injection: the dynamic system-prompt section that makes
+ * `prompt` entries visible to the model without a tool call, and `subagent`
+ * entries available as reusable delegation specs at the delegation seam.
+ *
+ * Design (design.md §7 Phase 2):
+ * - the section text is a provider evaluated at every assembly with the
+ *   assembling agent; a section that renders to "" is dropped by the prompt
+ *   renderer, so an empty store costs zero tokens;
+ * - prompt entries render as an additive section (the base system prompt is
+ *   never touched); subagent entries render as delegation specs the parent
+ *   follows when delegating, and are inherited by child agents through the
+ *   `SessionHeader.parentSession` chain so a freshly spawned subagent carries
+ *   its parent's specs without any provider wrapping;
+ * - every cap mirrors render.ts (6 entries/kind, 180 chars/entry, stable
+ *   sort), keeping the injected cost bounded no matter how the store grows;
+ * - full text stays one `evolve_list` call away: the injected block is a
+ *   summary index, not a duplicate of the store.
+ */
+import type { HarnessEntry, HarnessState } from "./types.js";
+import type { EvolutionEngine } from "./service.js";
+/** Prompt sections render at most this many entries per kind. */
+export declare const MAX_INJECTED_ENTRIES_PER_KIND = 6;
+/** Per-entry content budget inside the injected block (matches render.ts). */
+export declare const MAX_INJECTED_CONTENT_LENGTH = 180;
+/** How many `parentSession` hops a child walks to inherit entries. */
+export declare const MAX_PARENT_CHAIN_DEPTH = 8;
+/** Recency half-life for the injection ranking: an entry this old scores 0. */
+export declare const RECENCY_HALF_LIFE_MS: number;
+/** At most this many recent user messages feed the relevance query. */
+export declare const MAX_QUERY_MESSAGES = 3;
+/** Query text handed to the relevance scorer is capped at this many chars. */
+export declare const MAX_QUERY_CHARS = 400;
+/** A user-message event's durable shape, loosened for duck typing. */
+export interface UserMessageEventLike {
+    type?: string;
+    data?: {
+        content?: unknown;
+        source?: {
+            kind?: string;
+        };
+    };
+}
+/** The minimal agent shape the section provider needs (duck-typed). */
+export interface AgentLike {
+    id: string;
+    session?: {
+        header?: {
+            parentSession?: string;
+        };
+        /**
+         * Live append-only session log. Typed loosely (`unknown[]`) so the real
+         * `SessionEvent[]` union from dsh-session is assignable; rows are
+         * narrowed to {@link UserMessageEventLike} at read time.
+         */
+        events?: readonly unknown[];
+    };
+}
+/** The section-provider context shape we consume (subset of AssembleContext). */
+export interface InjectContext {
+    agent?: AgentLike;
+}
+/**
+ * Lowercase tokenization for the keyword relevance scorer: runs of ASCII
+ * alphanumerics and CJK characters become tokens (CJK is not split so whole
+ * Chinese words/characters stay comparable), everything else is a separator.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Keyword hit count of `query` tokens inside an entry: title hits weigh 2×,
+ * content/path hits 1×. BM25-level relevance without any external service.
+ */
+export declare function relevanceHits(entry: HarnessEntry, query: string): number;
+/**
+ * Normalized recency in [0, 1]: 1 when the entry was just updated, decaying
+ * linearly to 0 after {@link RECENCY_HALF_LIFE_MS}. Unparseable timestamps
+ * score 0 (never preferred over a timestamped entry).
+ */
+export declare function recencyScore(entry: HarnessEntry, now: number): number;
+/**
+ * Rank entries for injection, best first. With no query the ranking is pure
+ * recency (newest first). With a query, any entry with at least one keyword
+ * hit outranks every hit-less entry (`hits * 2 + recency <= 1` for the
+ * latter), and hits decide the order among relevant entries; recency then
+ * breaks remaining ties, and the stable dictionary order is the final
+ * tiebreak, so the result is deterministic.
+ */
+export declare function rankEntries(entries: readonly HarnessEntry[], query?: string, now?: number): HarnessEntry[];
+/**
+ * Compose the relevance query from the assembling agent's most recent direct
+ * user messages (event rows whose `type` is `user/message` and whose source
+ * is a human `user`, so injected plugin context and tool results never leak
+ * into the query). Returns "" when nothing qualifies — the ranking then
+ * falls back to pure recency.
+ */
+export declare function recentUserText(agent: AgentLike | undefined, opts?: {
+    maxMessages?: number;
+    maxChars?: number;
+}): string;
+/** True when the state carries at least one entry of any kind. */
+export declare function hasAnyEntries(state: HarnessState): boolean;
+/** The additive prompt-notes block (empty when there are no visible prompt entries). */
+export declare function formatPromptEntriesSection(entries: readonly HarnessEntry[], query?: string): string;
+/** The reusable delegation-specs block (empty when there are no visible subagent entries). */
+export declare function formatSubagentSpecsSection(entries: readonly HarnessEntry[], query?: string): string;
+/**
+ * Walk the parent-session chain from `agent` upward and return the nearest
+ * session whose local store is non-empty, if any. Children inherit their
+ * ancestor's prompt notes and delegation specs; the chain walk stops at the
+ * first store that has entries (deep descendants do not re-inject ancestors
+ * beyond the nearest carrying store).
+ */
+export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, agent: AgentLike): HarnessState | undefined;
+/**
+ * Compose the full injected block for one assembling agent: global entries
+ * merged with the nearest carrying local store (local wins on id collision).
+ * The optional `query` — when absent, derived from the agent's most recent
+ * direct user messages — ranks which entries fill the per-kind cap
+ * (relevance first, then recency; see {@link rankEntries}). Returns "" when
+ * nothing is injectable — the prompt renderer then drops the section, so an
+ * empty store adds zero tokens to every assembly.
+ */
+export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string): string;
+//# sourceMappingURL=inject.d.ts.map