@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/types/learn-prompt.js

@@ -0,0 +1,42 @@
+/**
+ * Open-ended `/evolution learn` prompt builder.
+ *
+ * `learn` is open-ended: the user can name anything they can describe — a
+ * directory of code, an API doc URL, a workflow they just walked the agent
+ * through, or pasted notes. The prompt instructs the live agent to gather the
+ * named sources with its existing tools, then author a single SKILL.md via
+ * `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+ * distillation engine and no model-tool footprint.
+ */
+/**
+ * Build the agent prompt for an open-ended `/evolution learn` request.
+ *
+ * @param userRequest free-text the user gave after `/evolution learn`; an
+ *   empty string falls back to "the workflow we just went through".
+ * @returns a complete instruction the agent runs as a normal turn.
+ */
+export function buildLearnPrompt(userRequest) {
+    const request = userRequest.trim();
+    const resolved = request || 'the workflow we just went through in this conversation — review the steps taken and distill them into a reusable skill';
+    return [
+        '[/learn] The user wants you to learn a reusable skill from the request below, and save it.',
+        '',
+        'THE REQUEST:',
+        resolved,
+        '',
+        'The request is open-ended and may mix two kinds of content, in any order: SOURCES to gather (directories, file paths, URLs, "what we just did", pasted notes) AND REQUIREMENTS that shape the skill (what to focus on, what to leave out, scope, naming, the angle to take). Treat EVERY part of the request as load-bearing. In particular, prose that comes after a path or link is NOT incidental — it is the user telling you what they want from that source. A request like `<url> focus on the auth flow, skip the deprecated endpoints` means: gather the URL AND honor "focus on auth, skip deprecated" as authoring requirements. Never fetch the first source and ignore the rest.',
+        '',
+        'Do this:',
+        '1. Gather every source the user named, using the tools you already have — reads and searches for local files or directories, web access for URLs, this conversation history if they referred to something you just did, and the text they pasted as-is. If the request is ambiguous about scope, make a reasonable choice and note it; do not stall.',
+        '2. Author ONE SKILL.md, applying every requirement, focus, and constraint in the request — these govern what the SKILL.md covers and emphasizes, not just which sources you read.',
+        "3. Save it with the `skill_manage` tool (action=\"create\"). Pick a sensible category. If the procedure needs a non-trivial script, add it under the skill's `scripts/` with `skill_manage` write_file and reference it by relative path.",
+        '',
+        // P2-25 (v39): the standards live in the `skill_manage` tool description,
+        // which is in context on every turn that can call it — embedding them here
+        // repeated 1840 chars in this one (measured on the constant).
+        'Apply the skill-authoring standards (frontmatter, prose, file layout) carried by the `skill_manage` tool description — that is the single copy; do not restate them here.',
+        '',
+        'When done, tell the user the skill name, its category, and a one-line summary of what it captured.',
+    ].join('\n');
+}
+//# sourceMappingURL=learn-prompt.js.map

package/lib/types/limits.js

@@ -0,0 +1,63 @@
+/**
+ * Skill content limits: the byte/char budgets every write path validates against.
+ *
+ * Split out of skill-store.ts (S2-1) so the frontmatter validators and the
+ * store share one declaration site. Re-exported by skill-store.ts: the package
+ * export surface is unchanged.
+ */
+import { DEFAULT_SKILL_VERSION_KEEP, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH } from "./constants.js";
+/** `verify` checks that every cited target exists and otherwise allows the move;
+ * `refuse` restores the pre-0.5 behaviour of refusing ANY citation-carrying
+ * section. Resolved at the call site, so every existing limits object keeps
+ * working (unknown policy never silently changes a write path). */
+export const DEFAULT_CITATION_POLICY = 'verify';
+/** Default: report the plan on refusal, never write (behaviour unchanged). */
+export const DEFAULT_REFERENCE_REWRITE_POLICY = 'plan';
+/** Default: report-only, because upstream's hard invariant is never to delete. */
+export const DEFAULT_ARCHIVE_RETENTION_POLICY = 'report';
+/** Default: report, so the cap cannot brick an existing oversize file on upgrade
+ * (the live library carries a 189k-character release log today). */
+export const DEFAULT_SUPPORT_FILE_CHAR_POLICY = 'report';
+/** The four stage defaults in ONE object, so the policy schema's `z.default(...)`
+ * calls and the store's fallbacks cannot drift apart. */
+export const POLICY_STAGE_DEFAULTS = Object.freeze({
+    citationPolicy: DEFAULT_CITATION_POLICY,
+    referenceRewrite: DEFAULT_REFERENCE_REWRITE_POLICY,
+    archiveRetention: DEFAULT_ARCHIVE_RETENTION_POLICY,
+    supportFileCharPolicy: DEFAULT_SUPPORT_FILE_CHAR_POLICY,
+});
+/**
+ * The ONE conversion from the deployment policy snapshot to library limits
+ * (design §16.7): every plugin that owns a writable SkillLibrary spreads this into
+ * its limits, so a stage selected in cordis.yml reaches every write path. A
+ * per-plugin copy would be the third home for the same threshold.
+ *
+ * Only PRESENT fields are copied: an absent policy field must fall through to the
+ * library default rather than pinning `undefined` onto an optional limit (which
+ * `exactOptionalPropertyTypes` forbids and which would defeat the `?? DEFAULT`
+ * resolution inside the store).
+ * @param snapshot - the evolutionPolicy snapshot, or undefined when unmounted.
+ * @returns the stage fields the snapshot actually carries.
+ */
+export function policyStageLimits(snapshot) {
+    if (snapshot === undefined)
+        return {};
+    const stages = {};
+    if (snapshot.citationPolicy !== undefined)
+        stages.citationPolicy = snapshot.citationPolicy;
+    if (snapshot.referenceRewrite !== undefined)
+        stages.referenceRewrite = snapshot.referenceRewrite;
+    if (snapshot.archiveRetention !== undefined)
+        stages.archiveRetention = snapshot.archiveRetention;
+    if (snapshot.supportFileCharPolicy !== undefined)
+        stages.supportFileCharPolicy = snapshot.supportFileCharPolicy;
+    return stages;
+}
+export const DEFAULT_SKILL_LIMITS = {
+    maxNameLength: MAX_SKILL_NAME_LENGTH,
+    maxDescriptionLength: MAX_DESCRIPTION_LENGTH,
+    maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
+    maxSkillFileBytes: MAX_SKILL_FILE_BYTES,
+    versionKeep: DEFAULT_SKILL_VERSION_KEEP,
+};
+//# sourceMappingURL=limits.js.map

package/lib/types/live.js

@@ -0,0 +1,107 @@
+/**
+ * The family's ONE live-config reader.
+ *
+ * A config field reaches a plugin in two shapes: the platform's schema parser turns a
+ * `.volatile()` declaration into a live reference (`{ get() }`, routed through cosmokit's
+ * `createVolatile`), while a hand-built or pre-parse config carries the plain value. Reading a
+ * live reference as if it were a value is SILENT (a boolean compare is simply never true, a
+ * number folds as NaN) — so the two shapes are unwrapped in exactly one place here, and every
+ * reader below goes through it.
+ *
+ * This module owns no policy: clamping semantics stay in `clampedNumber` (numeric.ts), and the
+ * once-per-key warning text/rhythm is the one `clampOnce` has always had (it moved here so the
+ * read happens in one place; callers import it from the package barrel, so the move is invisible).
+ *
+ * @module @lmzhen/dsh-evolution-core
+ */
+import { clampedNumber } from "./numeric.js";
+/**
+ * Unwrap a live reference; return a plain value unchanged. The ONLY place that decides the shape.
+ *
+ * The discriminant is `typeof get === 'function'` rather than a bare `typeof value === 'object'`: a
+ * config field may legitimately carry an object (a policy record), and calling `.get()` on that
+ * used to throw where a plain read was meant.
+ *
+ * @param value - the field as supplied: live reference, plain value, or absent.
+ * @returns the plain value, or `undefined` when the reference/field is absent.
+ */
+export function unwrapLive(value) {
+    // Read as unknown: the discriminant is a RUNTIME shape check, so every narrowing below is real
+    // (a null test against the declared union would be a tautology the linter rejects).
+    const raw = value;
+    if (typeof raw !== 'object' || raw === null)
+        return raw === undefined ? undefined : raw;
+    const candidate = raw;
+    return typeof candidate.get === 'function' ? candidate.get.call(raw) : raw;
+}
+/**
+ * Read a numeric knob (live or plain) and clamp it, warning ONCE per key.
+ *
+ * @param value - the field as supplied: live reference, plain value, or absent.
+ * @param fallback - the package default an invalid value falls back to.
+ * @param opts - bounds plus the optional warning triple.
+ * @returns the value the engine may use.
+ */
+export function liveNumber(value, fallback, opts = {}) {
+    const current = unwrapLive(value);
+    const { min, max } = opts;
+    // Built conditionally, not `{ min, max }`: under exactOptionalPropertyTypes a present-but-undefined
+    // property is not the same as an absent one, and clampedNumber's bounds are optional.
+    const bounds = min === undefined
+        ? (max === undefined ? undefined : { max })
+        : (max === undefined ? { min } : { min, max });
+    const result = clampedNumber(current, fallback, bounds);
+    const name = opts.name;
+    if (current !== undefined && result !== current && name !== undefined && opts.warn !== undefined) {
+        const warned = opts.warned ?? new Set();
+        if (!warned.has(name)) {
+            warned.add(name);
+            opts.warn(`${name} provided an invalid value; falling back to the default`);
+        }
+    }
+    return result;
+}
+/**
+ * Clamp one numeric knob and warn ONCE per key — the pre-0.22 signature, kept as a thin adapter so
+ * existing callers migrate one at a time instead of in one commit.
+ *
+ * @param warned - the keys this caller already warned about.
+ * @param warn - the warning sink (each package prefixes its own name).
+ * @param name - the config key, for the warning.
+ * @param value - the value as supplied, or its live reference.
+ * @param fallback - the package default a corrected value falls back to.
+ * @param min - the smallest value the engine can act on.
+ * @param max - the largest value the carrier can hold, when bounded.
+ * @returns the value the engine may use.
+ */
+export function clampOnce(warned, warn, name, value, fallback, min, max) {
+    return liveNumber(value, fallback, { min, ...(max === undefined ? {} : { max }), warned, warn, name });
+}
+/**
+ * Read a boolean flag (live or plain). Absent ⇒ `fallback` (default `false`).
+ *
+ * The boolean counterpart of {@link liveNumber}: `value === true` is never true for a live
+ * reference, which is the silent failure this reader exists to prevent.
+ */
+export function liveBool(value, fallback = false) {
+    return unwrapLive(value) ?? fallback;
+}
+/**
+ * Read a string (live or plain). Blank/whitespace counts as unset — the same rule `evolutionRoot` uses
+ * for `DSH_HOME`.
+ */
+export function liveString(value, fallback) {
+    const current = unwrapLive(value)?.trim();
+    return current === undefined || current.length === 0 ? fallback : current;
+}
+/**
+ * Read an enumerated string (live or plain); a value outside `allowed` falls back.
+ *
+ * Used for the mode-like knobs (review mode, trigger, citation policy, write-confirm mode) where a
+ * bare `?? default` would accept a typo the schema never saw.
+ */
+export function liveEnum(value, allowed, fallback) {
+    const current = unwrapLive(value);
+    return current !== undefined && allowed.includes(current) ? current : fallback;
+}
+//# sourceMappingURL=live.js.map

package/lib/types/long-runs.js

@@ -0,0 +1,96 @@
+/**
+ * 0.19.0 (S4): the family's long-run inventory — one table, one owner per entry.
+ *
+ * A "long run" is work whose duration is NOT bounded by the interaction that asked
+ * for it: a maintenance scan, a curator pass, a review pass. The measured fact this
+ * table exists to record is that a CLIENT can end a request long before the work is
+ * done (measured: the desktop shell ends a request at ~305 s while the same command
+ * finishes in 949.7 s on the web plane), so the lifetime of such work must come from
+ * its OWNER — never from the request.
+ *
+ * Two fields carry the judgments, and a spec pins both:
+ *
+ *   - `lifetime`: `'plugin'` entries must name an owner and a result home (the work
+ *     outlives the request and must be readable afterwards); `'request'` entries
+ *     must say WHY their cost cannot reach the wall.
+ *   - `measured`: only measured numbers, with their basis. An unmeasured bound is
+ *     written as exactly that — this table is not a place to guess.
+ *
+ * The rendered table is pinned byte-for-byte into `packages/README.md` by
+ * `tests/long-runs.spec.ts` (the T-WD2 pattern the command registry already uses),
+ * so the published table cannot drift from this list.
+ * @module
+ */
+/**
+ * The inventory. Order is the rendered order; a spec pins it into the README.
+ */
+export const LONG_RUNS = [
+    {
+        id: '/evolution maintain',
+        kind: 'command',
+        owner: 'evolution-commands',
+        lifetime: 'plugin',
+        measured: 'the same scan measured 949.7 s end to end on the web plane (no Electron); the desktop shell ends the REQUEST at ~305 s (four runs: 305.6/307.0/306.0/305.7 s)',
+        budget: 'maintainTimeoutMs (row config, default 600000) or --timeout <ms> for one run',
+        resultHome: '<evolutionHome>/reports/maintain-<runId>.{json,md}, indexed in <evolutionHome>/runs.json',
+        note: 'The ~305 s wall is a CLIENT lifetime, not a budget: the run keeps working and the result is read back with maintain status/report. Its cancellation is the run registry handle (maintain cancel <id>) or plugin dispose.',
+    },
+    {
+        id: 'maintenance_probe',
+        kind: 'tool',
+        owner: 'evolution-maintenance',
+        lifetime: 'request',
+        measured: '188/220/225 ms on the deployed library (28 skills / 418 KB); ~5.5 ms per skill and linear (100 skills 0.4-0.6 s, 400 skills 1.9-2.5 s)',
+        budget: 'none, deliberately: reaching the ~305 s wall would take roughly 5e4 skills',
+        resultHome: 'the tool result (JSON detail), answered in-turn',
+        note: 'O(2N) tree reads (enrichment + snapshot), uncached by design. Reopen the budget question when the library nears ~1e4 skills, when the io provider stops being local, or when a model leg enters a tool execute.',
+    },
+    {
+        id: 'skill_manage',
+        kind: 'tool',
+        owner: 'tool-skill-manage',
+        lifetime: 'request',
+        measured: 'not measured as a duration: single-file IO plus a library listing the cross-source gate already reads; the only unbounded wait is a HUMAN answer',
+        budget: 'its own gate deadline (skillWriteConfirm + pendingTtlMs) — a second budget here would compete with it',
+        resultHome: 'the tool result, plus the mutation audit records',
+        note: 'The human wait is the reason this entry exists: it is bounded by the write gate, which the tool owns.',
+    },
+    {
+        id: 'memory',
+        kind: 'tool',
+        owner: 'tool-memory',
+        lifetime: 'request',
+        measured: 'single-file IO on the memory store',
+        budget: 'none needed',
+        resultHome: 'the tool result',
+        note: 'No tree walk, no model leg, no human wait.',
+    },
+    {
+        id: 'curator pass',
+        kind: 'pass',
+        owner: 'evolution-curator',
+        lifetime: 'plugin',
+        measured: 'not measured end to end; the LLM nomination leg is bounded separately',
+        budget: 'curatorReviewTimeoutMs (E3 parameter) for the LLM leg',
+        resultHome: '<evolutionHome>/reports/curator-<runId>.{json,md}',
+        note: 'Runs from the plugin interval timer, and a failed or timed-out LLM leg is a distinguishable state in the run report (nominationsWarnings).',
+    },
+    {
+        id: 'review pass',
+        kind: 'pass',
+        owner: 'evolution-review',
+        lifetime: 'plugin',
+        measured: 'not measured end to end; the subagent leg carries its own deadline',
+        budget: 'reviewTimeoutMs (E2 parameter)',
+        resultHome: 'the review inbox plus evolution/plan-applied',
+        note: 'The write leg replays a staged plan through the registered runner; cancellation follows the plugin fiber.',
+    },
+];
+/**
+ * Render the inventory as the README table rows (no header).
+ * @returns one markdown row per entry, in inventory order.
+ */
+export function renderLongRunTable() {
+    return LONG_RUNS.map(entry => `| \`${entry.id}\` | ${entry.kind} | ${entry.owner} | ${entry.lifetime} | ${entry.measured} | ${entry.resultHome} |`).join('\n');
+}
+//# sourceMappingURL=long-runs.js.map

package/lib/types/memory-store.d.ts

@@ -23,22 +23,6 @@ export interface MemoryApplyResult {
     limit: number;
 }
 export declare function memoryRoot(env?: NodeJS.ProcessEnv): string;
-/**
- * Neutralize the platform's `{{name}}` prompt-variable syntax in text that is
- * about to be registered as a `systemPrompt.context` contribution.
- *
- * The platform interpolates every context/section text once per model step and
- * THROWS on an unknown or malformed reference — so one stored memory entry
- * containing `{{...}}` (a CI expression, a Jinja/Helm/Vue template, a doc
- * placeholder) used to fail `assemble()` on EVERY later pre-step of every
- * session under this DSH_HOME, while a registered name such as `{{cwd}}` was
- * silently substituted into the "memory" the model reads. Only the INJECTED
- * text is neutralized: stored entries keep their original bytes.
- *
- * @param text - rendered context text about to leave for the prompt surface.
- * @returns the same text with every `{{` split so it cannot start a reference.
- */
-export declare function neutralizePromptVariables(text: string): string;
 export interface MemoryStoreOptions {
     memoryCharLimit?: number;
     userCharLimit?: number;