dsh-continual-evolve 0.1.0

package/lib/inject.js

@@ -0,0 +1,231 @@
+import { isArchived } from "./types.js";
+import { mergeHarnessStates } from "./state.js";
+import { entryLine } from "./render.js";
+/** Prompt sections render at most this many entries per kind. */
+export const MAX_INJECTED_ENTRIES_PER_KIND = 6;
+/** Per-entry content budget inside the injected block (matches render.ts). */
+export const MAX_INJECTED_CONTENT_LENGTH = 180;
+/** How many `parentSession` hops a child walks to inherit entries. */
+export const MAX_PARENT_CHAIN_DEPTH = 8;
+/** Recency half-life for the injection ranking: an entry this old scores 0. */
+export const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
+/** At most this many recent user messages feed the relevance query. */
+export const MAX_QUERY_MESSAGES = 3;
+/** Query text handed to the relevance scorer is capped at this many chars. */
+export const MAX_QUERY_CHARS = 400;
+/** Stable dictionary-order tiebreak used when two entries score equally. */
+function stableCompare(a, b) {
+    return [a.path, a.title, a.id].join("\0").localeCompare([b.path, b.title, b.id].join("\0"));
+}
+/**
+ * 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 function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9\u4e00-\u9fff]+/)
+        .filter((token) => token.length > 0);
+}
+/**
+ * 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 function relevanceHits(entry, query) {
+    const titleTokens = tokenize(entry.title);
+    const bodyTokens = tokenize(`${entry.content} ${entry.path}`);
+    let hits = 0;
+    for (const token of tokenize(query)) {
+        hits += titleTokens.filter((t) => t === token).length * 2;
+        hits += bodyTokens.filter((t) => t === token).length;
+    }
+    return hits;
+}
+/**
+ * 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 function recencyScore(entry, now) {
+    const updatedAt = Date.parse(entry.updated_at);
+    if (Number.isNaN(updatedAt)) {
+        return 0;
+    }
+    const age = now - updatedAt;
+    if (age <= 0) {
+        return 1;
+    }
+    return Math.max(0, 1 - age / RECENCY_HALF_LIFE_MS);
+}
+/**
+ * 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 function rankEntries(entries, query, now = Date.now()) {
+    const q = (query ?? "").trim();
+    return [...entries].sort((a, b) => {
+        if (q.length > 0) {
+            const relevanceDelta = relevanceHits(b, q) * 2 - relevanceHits(a, q) * 2;
+            if (relevanceDelta !== 0) {
+                return relevanceDelta;
+            }
+        }
+        const recencyDelta = recencyScore(b, now) - recencyScore(a, now);
+        if (recencyDelta !== 0) {
+            return recencyDelta;
+        }
+        return stableCompare(a, b);
+    });
+}
+function sortedEntries(entries, query) {
+    return rankEntries(entries, query);
+}
+/**
+ * Extract the text of a message's content blocks without depending on the
+ * dsh-llm ContentBlock type: string blocks pass through, object blocks
+ * contribute their `text` field when present.
+ */
+function extractBlockText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    return content
+        .map((block) => {
+        if (typeof block === "string") {
+            return block;
+        }
+        if (block !== null && typeof block === "object" && "text" in block && typeof block.text === "string") {
+            return block.text;
+        }
+        return "";
+    })
+        .filter((text) => text.length > 0)
+        .join(" ");
+}
+/**
+ * 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 function recentUserText(agent, opts) {
+    const events = agent?.session?.events;
+    if (!events || events.length === 0) {
+        return "";
+    }
+    const maxMessages = opts?.maxMessages ?? MAX_QUERY_MESSAGES;
+    const maxChars = opts?.maxChars ?? MAX_QUERY_CHARS;
+    const parts = [];
+    for (let i = events.length - 1; i >= 0 && parts.length < maxMessages; i -= 1) {
+        const event = events[i];
+        if (event?.type !== "user/message") {
+            continue;
+        }
+        const source = event.data?.source;
+        if (source && source.kind !== "user") {
+            continue;
+        }
+        const text = extractBlockText(event.data?.content).trim();
+        if (text.length > 0) {
+            parts.unshift(text);
+        }
+    }
+    return parts.join(" ").slice(0, maxChars);
+}
+/** True when the state carries at least one entry of any kind. */
+export function hasAnyEntries(state) {
+    return Object.values(state.entries).some((byKind) => Object.keys(byKind).length > 0);
+}
+/** The additive prompt-notes block (empty when there are no visible prompt entries). */
+export function formatPromptEntriesSection(entries, query) {
+    const visible = entries.filter((entry) => !isArchived(entry));
+    if (visible.length === 0) {
+        return "";
+    }
+    const lines = [
+        "# Continual Harness — Prompt Notes",
+        "Supplemental prompt notes (the base system prompt is immutable). Use evolve_list for the full text of any note.",
+    ];
+    for (const entry of sortedEntries(visible, query).slice(0, MAX_INJECTED_ENTRIES_PER_KIND)) {
+        lines.push(entryLine(entry, MAX_INJECTED_CONTENT_LENGTH));
+    }
+    const overflow = visible.length - Math.min(visible.length, MAX_INJECTED_ENTRIES_PER_KIND);
+    if (overflow > 0) {
+        lines.push(`- +${overflow} more prompt notes (evolve_list)`);
+    }
+    return lines.join("\n");
+}
+/** The reusable delegation-specs block (empty when there are no visible subagent entries). */
+export function formatSubagentSpecsSection(entries, query) {
+    const visible = entries.filter((entry) => !isArchived(entry));
+    if (visible.length === 0) {
+        return "";
+    }
+    const lines = [
+        "# Continual Harness — Delegation Specs",
+        "Reusable subagent specs: when you delegate work that matches a spec, assemble the child prompt from its content. Children inherit these specs through their parent chain.",
+    ];
+    for (const entry of sortedEntries(visible, query).slice(0, MAX_INJECTED_ENTRIES_PER_KIND)) {
+        lines.push(entryLine(entry, MAX_INJECTED_CONTENT_LENGTH));
+    }
+    const overflow = visible.length - Math.min(visible.length, MAX_INJECTED_ENTRIES_PER_KIND);
+    if (overflow > 0) {
+        lines.push(`- +${overflow} more delegation specs (evolve_list)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 function nearestLocalStateWithEntries(engine, agent) {
+    let cursor = agent;
+    for (let depth = 0; cursor !== undefined && depth < MAX_PARENT_CHAIN_DEPTH; depth += 1) {
+        const state = engine.load("local", cursor.id);
+        if (hasAnyEntries(state)) {
+            return state;
+        }
+        cursor = cursor.session?.header?.parentSession
+            ? { id: cursor.session.header.parentSession }
+            : undefined;
+    }
+    return 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 function entriesSectionText(engine, agent, query) {
+    if (!agent) {
+        return "";
+    }
+    const globalState = engine.load("global", undefined);
+    const localState = nearestLocalStateWithEntries(engine, agent);
+    const merged = localState ? mergeHarnessStates(globalState, localState) : globalState;
+    const promptEntries = Object.values(merged.entries.prompt);
+    const subagentEntries = Object.values(merged.entries.subagent);
+    const relevanceQuery = (query ?? recentUserText(agent)).trim();
+    const parts = [
+        formatPromptEntriesSection(promptEntries, relevanceQuery),
+        formatSubagentSpecsSection(subagentEntries, relevanceQuery),
+    ].filter((part) => part.length > 0);
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=inject.js.map

package/lib/logfile.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Plugin-owned file logging: a cordis logger exporter that appends every
+ * log message — from this plugin or any other — to a JSONL file under the
+ * evolve store. Logging becomes a property of the plugin itself: no extra
+ * component to install, and it works no matter how `dsh web` is launched
+ * (foreground terminal, nohup, restart scripts, ...). The official
+ * `cordis-plugin-logger-console` remains an optional add-on for live
+ * terminal output; this file exporter is the baseline that always exists.
+ *
+ * - file: `<baseDir>/evolve/plugin.log` (0600, JSONL)
+ * - rotation: when the file exceeds `logMaxBytes` it is renamed to
+ *   `plugin.log.1` (replacing the previous `.1`)
+ * - level: `levels.default` = logLevel (0=error, 1=info, 2=warn, 3=debug)
+ * - failure containment: a write error is swallowed — logging never
+ *   disturbs the agent loop
+ */
+import type { Context } from "@deepseek-ai/cordis";
+/** Name of the plugin log file under `<baseDir>/evolve/`. */
+export declare const PLUGIN_LOG_FILE_NAME = "plugin.log";
+/** Default rotation threshold (5 MiB). */
+export declare const DEFAULT_LOG_MAX_BYTES: number;
+export interface FileLoggerConfig {
+    /** 0=error, 1=info, 2=warn, 3=debug. */
+    logLevel?: number;
+    /** Rotate the log when it exceeds this many bytes. */
+    logMaxBytes?: number;
+}
+/** Full path of the plugin log file. */
+export declare function pluginLogFilePath(baseDir: string): string;
+/** JSON-safe rendering of a log message's arguments. */
+export declare function renderArgs(args: readonly unknown[]): unknown[];
+/** One JSONL record as written to the log file. */
+export declare function logRecord(message: {
+    ts: number;
+    type: string;
+    name: string;
+    args: readonly unknown[];
+}): string;
+/** Human-readable rendering of one stored JSONL line (unparseable lines pass through). */
+export declare function formatLogLine(line: string): string;
+/**
+ * The distinct session ids mentioned in one stored log line, drawn from the
+ * rendered message and the raw args (unparseable lines fall back to a raw
+ * text scan). Exact-token matching, so `session-abc` never matches
+ * `session-abcd`.
+ */
+export declare function sessionIdsInLine(line: string): string[];
+/**
+ * Keep only the lines mentioning the given session id (exact token match).
+ * An empty/whitespace session id filters everything out — the caller should
+ * validate the argument before calling.
+ */
+export declare function filterLogBySession(lines: readonly string[], sessionId: string): string[];
+/** Append one line, rotating the file first when it exceeds maxBytes. */
+export declare function appendOrRotate(path: string, maxBytes: number, line: string): void;
+/**
+ * Register the file exporter on the context. Returns the exporter so tests
+ * can drive it directly. The exporter is disposed with the plugin's scope.
+ */
+export declare function registerFileLogger(ctx: Context, baseDir: string, config?: FileLoggerConfig): {
+    levels: {
+        default: number;
+    };
+    export(message: {
+        ts: number;
+        type: string;
+        name: string;
+        args: readonly unknown[];
+    }): void;
+};
+//# sourceMappingURL=logfile.d.ts.map

package/lib/logfile.js

@@ -0,0 +1,159 @@
+import { Logger } from "@deepseek-ai/cordis";
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Name of the plugin log file under `<baseDir>/evolve/`. */
+export const PLUGIN_LOG_FILE_NAME = "plugin.log";
+/** Default rotation threshold (5 MiB). */
+export const DEFAULT_LOG_MAX_BYTES = 5 * 1024 * 1024;
+/** Full path of the plugin log file. */
+export function pluginLogFilePath(baseDir) {
+    return join(baseDir, "evolve", PLUGIN_LOG_FILE_NAME);
+}
+/** JSON-safe rendering of a log message's arguments. */
+export function renderArgs(args) {
+    return args.map((arg) => {
+        if (arg instanceof Error) {
+            return { name: arg.name, message: arg.message, stack: arg.stack };
+        }
+        if (typeof arg === "object" && arg !== null) {
+            try {
+                return JSON.parse(JSON.stringify(arg));
+            }
+            catch {
+                return String(arg);
+            }
+        }
+        return arg;
+    });
+}
+/** One JSONL record as written to the log file. */
+export function logRecord(message) {
+    // `message` is the printf-rendered text (cordis handles %s/%o/...), so
+    // humans and machines both get a usable line; `args` keeps the raw
+    // payload for tooling. Errors render as their stack (JSON.stringify of
+    // an Error is just {}).
+    const rendered = Logger.format({
+        formatters: {
+            o: (value) => (value instanceof Error ? value.stack ?? value.message : JSON.stringify(value)),
+        },
+        maxLength: 10240,
+        export: () => { },
+    }, {
+        sn: 0,
+        ts: message.ts,
+        name: message.name,
+        type: message.type,
+        level: 0,
+        args: message.args,
+    });
+    return JSON.stringify({
+        ts: new Date(message.ts).toISOString(),
+        type: message.type,
+        name: message.name,
+        args: renderArgs(message.args),
+        message: rendered,
+    });
+}
+/** Human-readable rendering of one stored JSONL line (unparseable lines pass through). */
+export function formatLogLine(line) {
+    try {
+        const record = JSON.parse(line);
+        const ts = record.ts ?? "";
+        const type = record.type ? `[${record.type[0]?.toUpperCase() ?? "?"}]` : "[?]";
+        const name = record.name ?? "";
+        const body = typeof record.message === "string" && record.message.length > 0 ? record.message : "";
+        const args = body
+            ? ""
+            : Array.isArray(record.args)
+                ? record.args.map((arg) => (typeof arg === "object" && arg !== null ? JSON.stringify(arg) : String(arg))).join(" ")
+                : "";
+        return `${ts} ${type} ${name} ${body || args}`.trimEnd();
+    }
+    catch {
+        return line;
+    }
+}
+/** A session id as it appears in log text (dsh `session-<hex-uuid>` ids). */
+const SESSION_TOKEN_RE = /\bsession-[0-9a-fA-F-]+\b/g;
+/**
+ * The distinct session ids mentioned in one stored log line, drawn from the
+ * rendered message and the raw args (unparseable lines fall back to a raw
+ * text scan). Exact-token matching, so `session-abc` never matches
+ * `session-abcd`.
+ */
+export function sessionIdsInLine(line) {
+    const ids = [];
+    const collect = (text) => {
+        for (const match of text.matchAll(SESSION_TOKEN_RE)) {
+            ids.push(match[0]);
+        }
+    };
+    try {
+        const record = JSON.parse(line);
+        if (typeof record.message === "string")
+            collect(record.message);
+        if (Array.isArray(record.args)) {
+            for (const arg of record.args) {
+                collect(typeof arg === "object" && arg !== null ? JSON.stringify(arg) : String(arg));
+            }
+        }
+    }
+    catch {
+        collect(line);
+    }
+    return [...new Set(ids)];
+}
+/**
+ * Keep only the lines mentioning the given session id (exact token match).
+ * An empty/whitespace session id filters everything out — the caller should
+ * validate the argument before calling.
+ */
+export function filterLogBySession(lines, sessionId) {
+    const needle = sessionId.trim();
+    if (!needle) {
+        return [];
+    }
+    return lines.filter((line) => sessionIdsInLine(line).includes(needle));
+}
+/** Append one line, rotating the file first when it exceeds maxBytes. */
+export function appendOrRotate(path, maxBytes, line) {
+    const dir = dirname(path);
+    if (!existsSync(path)) {
+        mkdirSync(dir, { recursive: true });
+        // 0600: the log can carry session context and must not be world-readable
+        writeFileSync(path, "", { encoding: "utf8", mode: 0o600 });
+    }
+    if (maxBytes > 0) {
+        try {
+            if (statSync(path).size > maxBytes) {
+                renameSync(path, `${path}.1`);
+            }
+        }
+        catch {
+            // stat/rename failures fall through to the append attempt
+        }
+    }
+    appendFileSync(path, `${line}\n`, "utf8");
+}
+/**
+ * Register the file exporter on the context. Returns the exporter so tests
+ * can drive it directly. The exporter is disposed with the plugin's scope.
+ */
+export function registerFileLogger(ctx, baseDir, config = {}) {
+    const path = pluginLogFilePath(baseDir);
+    const maxBytes = config.logMaxBytes ?? DEFAULT_LOG_MAX_BYTES;
+    const exporter = {
+        levels: { default: config.logLevel ?? 1 },
+        export(message) {
+            try {
+                appendOrRotate(path, maxBytes, logRecord(message));
+            }
+            catch {
+                // logging must never disturb the agent loop
+            }
+        },
+    };
+    ctx.logger.exporter(exporter);
+    return exporter;
+}
+//# sourceMappingURL=logfile.js.map

package/lib/mount.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { HarnessEntry } from "./types.js";
+export interface MountRecord {
+    id: string;
+    /** Loader entry id (the `evolve:<name>` key). */
+    entryId: string;
+    /** Absolute path of the generated plugin package. */
+    path: string;
+    /** Entry revision the mount was generated from. */
+    version: number;
+    mountedAt: string;
+}
+export interface MountLedger {
+    mounted: MountRecord[];
+}
+export declare function mountedDir(baseDir: string): string;
+export declare function ledgerPath(baseDir: string): string;
+export declare function loadLedger(baseDir: string): MountLedger;
+export declare function saveLedger(baseDir: string, ledger: MountLedger): void;
+/** Generate the plugin package files for one skill entry; returns the package dir. */
+export declare function renderMountPackage(baseDir: string, entry: HarnessEntry): string;
+/** The generated plugin source: one tool registration, no external imports. */
+export declare function renderPluginSource(toolName: string, entry: HarnessEntry): string;
+/**
+ * Map a skill entry's arguments contract to the tool-parameter schema.
+ * Requiredness goes in a root-level `required` array (valid JSON Schema):
+ * the mounted plugin registers via raw `ctx.tools.register`, and dsh-llm
+ * sends `parameters` verbatim to the API, which rejects per-property
+ * `required: true` ("true is not of type array").
+ */
+export declare function renderParameters(entry: HarnessEntry): Record<string, unknown>;
+/**
+ * Mount one skill entry into the live loader. Requires the `loader` service
+ * (resolved lazily, see FAQ #1); without it the package is still written and
+ * the ledger records the entry for the next boot.
+ */
+export declare function mountSkill(ctx: Context, baseDir: string, entry: HarnessEntry): Promise<MountRecord>;
+/** Unmount a skill entry: remove the loader entry and the generated package. */
+export declare function unmountSkill(ctx: Context, baseDir: string, id: string): Promise<MountRecord | undefined>;
+/** Re-mount every ledger entry at plugin boot (restart persistence). */
+export declare function restoreMounted(ctx: Context, baseDir: string): Promise<void>;
+//# sourceMappingURL=mount.d.ts.map