@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/types/state-store.js

@@ -0,0 +1,60 @@
+/**
+ * Evolution home path helpers: the DSH root and `$DSH_HOME/evolution` for
+ * plugin-owned sidecar state (reports, activity store, feedback file,
+ * state-domain data).
+ *
+ * C-10: PATH HELPERS ONLY — despite the file name there is no store
+ * here. Durable evolution state lives in the state stack (evolution-state over
+ * evolution-state-json / -domain); skills and memories live in skill-store.ts
+ * / memory-store.ts. The file name is kept deliberately: renaming it would
+ * touch every family import for zero behavior change, and the audit records
+ * the mismatch as known naming debt.
+ */
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * DSH home root: `$DSH_HOME` or `~/.dsh`. Single source of the empty-string
+ * fallback — an EMPTY or WHITESPACE-ONLY DSH_HOME resolves to the default
+ * home, never to a CWD-relative path (0.3.19 W1.3, 0.3.22 F-207);
+ * V8-06 (0.3.47) extends the guard to whitespace.
+ * C-11 correction (S2.2, PLAN 2026-09-16): upstream `resolveDshHome`
+ * (util/home-paths) uses `trim()` ONLY as the ADOPTION test and then uses the
+ * RAW env value — the earlier "same trimmed source" form returned the trimmed
+ * text, so `DSH_HOME=" /x "` produced `/x` where upstream produced the literal
+ * padded path. The value semantics now match upstream line for line:
+ * `const selected = configured ?? (fromEnv !== undefined &&
+ * fromEnv.trim().length > 0 ? fromEnv : defaultDshHome())`.
+ * OPT-27 (2026-09, plan D5 — accepted): the v10-era "no `~` expansion, no
+ * resolve" divergence from upstream `resolveDshHome` is RETIRED. It became
+ * load-bearing when the skill-catalog shadow made "same tree as the upstream
+ * `USER_DSH_RANK` provider" a hard contract: upstream watches the EXPANDED
+ * absolute `<home>/skills` while this value fed a literal `~/x` (a directory
+ * named `~` under the host CWD) or a CWD-relative path — split-brain skill
+ * trees, preset installs the platform never reads, doctor probes of a
+ * directory nothing serves.
+ * S2.2 (PLAN 2026-09-16), final correction: the result is ALWAYS
+ * `resolve(expandHomePath(selected))` — the earlier form returned an
+ * already-absolute value VERBATIM, so a trailing slash or `..` segment
+ * landed unnormalized while upstream normalizes every value. Relative
+ * `DSH_HOME` values change landing spot; a CLEAN absolute home stays
+ * byte-identical (resolve is a no-op on it).
+ */
+export function evolutionRoot(env = process.env) {
+    const fromEnv = env.DSH_HOME;
+    const selected = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), '.dsh');
+    // Mirror upstream expandHomePath (util/home-paths): `~` alone is the OS
+    // home; `~/` and `~\` prefix the OS home; anything else is taken literally
+    // — then resolved to an absolute path like upstream resolveDshHome.
+    const expanded = selected === '~'
+        ? homedir()
+        : selected.startsWith('~/') || selected.startsWith('~\\')
+            ? join(homedir(), selected.slice(2))
+            : selected;
+    return resolve(expanded);
+}
+/** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+ * state (reports, activity store, feedback file, state-domain data). */
+export function evolutionHome(env = process.env) {
+    return join(evolutionRoot(env), 'evolution');
+}
+//# sourceMappingURL=state-store.js.map

package/lib/types/store-ledger.js

@@ -0,0 +1,117 @@
+/**
+ * G3/3.2 (audit 06-performance.md 接缝 C): ONE declaration for every bounded store.
+ *
+ * Before this file the family had eight retention rules scattered across four packages and no place
+ * that could answer "how long does this record live under the current policy" (S1.md 4.3): six caps
+ * were named constants, three lived inline (snapshots 5, reports 20/20/10, archive 365d). Each entry
+ * below states its bound AND the code that declares it, so a gate can compare the two sets.
+ *
+ * `declare` is an ARRAY because one store may have several declaration sites (the report buckets are
+ * kept by two packages). The `inline` branch matches a CODE SNIPPET rather than a line number: line
+ * numbers rot on every edit above them, a snippet survives (and a snippet that stops matching is the
+ * detector the gate wants). No naming convention is assumed anywhere - that is the whole point of a
+ * ledger: the list IS the declaration.
+ */
+/** The one list. A new bounded store that is not registered here is what the G3 gate refuses. */
+export const STORE_LEDGER = [
+    {
+        id: 'archive-entries',
+        owner: 'evolution-core',
+        unit: 'entries',
+        bound: '365 days, report-only by default (the removal policy is report, not delete)',
+        cutoff: 'archivedAt older than the retention window',
+        trigger: 'run-end',
+        artifact: 'count of .archive entries and their ages',
+        declare: [
+            // The window and the policy are two declarations on purpose: the bound is the window, and the
+            // policy decides whether crossing it deletes or only reports (audit S1-01: the message promised
+            // recoverability from a snapshot chain that is five deep).
+            { kind: 'inline', file: 'packages/evolution-core/src/skill-store.ts', contains: 'ARCHIVE_RETENTION_DAYS = 365', value: '365 days' },
+            { kind: 'named', module: 'evolution-core/src/limits.ts', name: 'DEFAULT_ARCHIVE_RETENTION_POLICY', value: 'report' },
+        ],
+    },
+    {
+        id: 'skill-snapshots',
+        owner: 'evolution-core',
+        unit: 'entries',
+        bound: '5 snapshots',
+        cutoff: 'oldest snapshot beyond the keep window',
+        trigger: 'run-end',
+        artifact: 'snapshot count and total bytes',
+        declare: [{ kind: 'inline', file: 'packages/evolution-core/src/skill-store.ts', contains: 'retainSnapshots(5)', value: '5' }],
+    },
+    {
+        id: 'skill-versions',
+        owner: 'evolution-core',
+        unit: 'entries',
+        bound: '20 versions per skill',
+        cutoff: 'history index entries beyond versionKeep',
+        trigger: 'write',
+        artifact: 'history index length per skill',
+        declare: [{ kind: 'named', module: 'evolution-core/src/constants.ts', name: 'DEFAULT_SKILL_VERSION_KEEP', value: 20 }],
+    },
+    {
+        id: 'pending-resolved',
+        owner: 'evolution-state-storage',
+        unit: 'entries',
+        bound: '200 resolved pending records',
+        cutoff: 'resolved records beyond the cap',
+        trigger: 'write',
+        artifact: 'resolved record count',
+        declare: [{ kind: 'named', module: 'evolution-state-storage/src/constants.ts', name: 'PENDING_RESOLVED_CAP', value: 200 }],
+    },
+    {
+        id: 'review-session',
+        owner: 'evolution-state-storage',
+        unit: 'entries',
+        bound: '500 review session rows',
+        cutoff: 'rows beyond the session cap',
+        trigger: 'write',
+        artifact: 'review state row count',
+        declare: [{ kind: 'named', module: 'evolution-state-storage/src/constants.ts', name: 'REVIEW_STATE_SESSION_CAP', value: 500 }],
+    },
+    {
+        id: 'reports',
+        owner: 'evolution-commands',
+        unit: 'files',
+        bound: '20/20/10 files across the three report buckets',
+        cutoff: 'reports beyond each bucket keep',
+        trigger: 'run-end',
+        artifact: 'report file count per bucket',
+        declare: [
+            { kind: 'inline', file: 'packages/evolution-commands/src/index.ts', contains: 'maintain-', value: '20' },
+            { kind: 'inline', file: 'packages/evolution-curator/src/index.ts', contains: 'errorKeep', value: '10' },
+        ],
+    },
+    {
+        id: 'event-archives',
+        owner: 'evolution-core',
+        unit: 'files',
+        bound: '10 archived event logs',
+        cutoff: 'archives beyond the retention count',
+        trigger: 'write',
+        artifact: 'event archive count',
+        declare: [{ kind: 'named', module: 'evolution-core/src/evolution-events.ts', name: 'EVENT_LOG_RETAIN_ARCHIVES', value: 10 }],
+    },
+    {
+        id: 'run-records',
+        owner: 'evolution-core',
+        unit: 'entries',
+        bound: '50 run records',
+        cutoff: 'runs beyond the record cap',
+        trigger: 'write',
+        artifact: 'runs.json record count',
+        declare: [{ kind: 'named', module: 'evolution-core/src/run-registry.ts', name: 'DEFAULT_RUN_RECORDS', value: 50 }],
+    },
+    {
+        id: 'support-reads',
+        owner: 'evolution-core',
+        unit: 'entries',
+        bound: '200 support_reads keys',
+        cutoff: 'keys beyond the read-path cap',
+        trigger: 'write',
+        artifact: 'usage sidecar key count',
+        declare: [{ kind: 'named', module: 'evolution-core/src/usage.ts', name: 'MAX_SUPPORT_READ_PATHS', value: 200 }],
+    },
+];
+//# sourceMappingURL=store-ledger.js.map

package/lib/types/subagent/channel.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { SubagentChannel } from './types.ts';
+export declare function createSubagentChannel(ctx: Context): SubagentChannel;
+//# sourceMappingURL=channel.d.ts.map

package/lib/types/subagent/channel.js

@@ -0,0 +1,131 @@
+import { ensureRestrictedPreset } from "../composition/ensure.js";
+import { probeChannelState } from "./readiness.js";
+function serviceOf(ctx, name) {
+    return ctx.get(name);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createSubagentChannel(ctx) {
+    let lastKind = 'reviewer';
+    const channel = {
+        get state() {
+            return probeChannelState(ctx, lastKind);
+        },
+        prepare(spec) {
+            lastKind = spec.kind;
+            const state = probeChannelState(ctx, spec.kind);
+            if (state.kind === 'unavailable')
+                return Promise.resolve(state);
+            if (spec.allow.length === 0)
+                return Promise.resolve({ kind: 'unavailable', code: 'E-324', reason: 'allow set is empty' });
+            return Promise.resolve(state);
+        },
+        async run(spec) {
+            lastKind = spec.kind;
+            const probe = probeChannelState(ctx, spec.kind);
+            if (probe.kind === 'unavailable')
+                return probe;
+            const subagents = serviceOf(ctx, 'subagents');
+            const presets = serviceOf(ctx, 'agentPresets');
+            if (subagents === undefined || presets === undefined) {
+                return { kind: 'unavailable', code: 'E-323', reason: 'subagents/agentPresets service unavailable' };
+            }
+            const parentPresetId = presets.composedPreset(spec.parent.ctx);
+            if (parentPresetId === undefined) {
+                return { kind: 'unavailable', code: 'E-323', reason: 'parent preset could not be resolved' };
+            }
+            const ensured = await ensureRestrictedPreset(ctx, { kind: spec.kind, parentPresetId, allow: spec.allow });
+            if (ensured.kind === 'failed') {
+                return { kind: 'unavailable', code: 'E-324', reason: ensured.reason };
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => { controller.abort(new Error('subagent timeout')); }, spec.timeoutMs);
+            const onAbort = () => { controller.abort(spec.signal?.reason); };
+            spec.signal?.addEventListener('abort', onAbort, { once: true });
+            let activation;
+            try {
+                activation = await subagents.startActivation({
+                    provider: 'spawn',
+                    label: spec.label,
+                    delivery: 'caller',
+                    request: {
+                        parent: spec.parent,
+                        prompt: [{ type: 'text', text: spec.promptText }],
+                        agentPreset: ensured.presetId,
+                        ...(spec.outputSchema !== undefined ? { outputSchema: spec.outputSchema } : {}),
+                        ...(spec.maxDepth !== undefined ? { maxDepth: spec.maxDepth } : {}),
+                        ...(spec.agentOptions !== undefined ? { agentOptions: spec.agentOptions } : {}),
+                    },
+                    signal: controller.signal,
+                });
+                let result;
+                try {
+                    result = await activation.result;
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        return { kind: 'aborted' };
+                    return { kind: 'unavailable', code: 'E-323', reason: messageOf(error) };
+                }
+                let evidence;
+                if (spec.afterResult !== undefined) {
+                    try {
+                        const agents = serviceOf(ctx, 'agents');
+                        const child = agents?.get(activation.childId);
+                        if (child !== undefined)
+                            evidence = spec.afterResult(child);
+                    }
+                    catch {
+                        evidence = undefined;
+                    }
+                }
+                const stopReason = result.stopReason;
+                // W5 §3: OK requires BOTH a completed stop and a structured payload; a completed run that
+                // produced nothing must stay a no-structured outcome so the business layer cannot treat an
+                // empty result as a plan.
+                if (stopReason === 'completed' && result.structured !== undefined && result.structured !== null) {
+                    return {
+                        kind: 'ok',
+                        structured: result.structured,
+                        childId: activation.childId,
+                        stopReason: 'completed',
+                        ...(evidence !== undefined ? { evidence } : {}),
+                    };
+                }
+                if (stopReason === 'aborted')
+                    return { kind: 'aborted' };
+                return {
+                    kind: 'no-structured',
+                    childId: activation.childId,
+                    stopReason,
+                    ...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic } : {}),
+                    ...(evidence !== undefined ? { evidence } : {}),
+                };
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return { kind: 'aborted' };
+                return { kind: 'unavailable', code: 'E-323', reason: messageOf(error) };
+            }
+            finally {
+                clearTimeout(timer);
+                spec.signal?.removeEventListener('abort', onAbort);
+                if (activation !== undefined) {
+                    try {
+                        await activation.dispose();
+                    }
+                    catch (error) {
+                        // W5 §6: teardown failures are observable but must NOT replace the captured outcome.
+                        try {
+                            ctx.logger.warn('subagent channel: activation dispose failed: ' + messageOf(error));
+                        }
+                        catch { /* logging must not mask teardown */ }
+                    }
+                }
+            }
+        },
+    };
+    return channel;
+}
+//# sourceMappingURL=channel.js.map

package/lib/types/subagent/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.ts';
+export * from './readiness.ts';
+export * from './channel.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/subagent/index.js

@@ -0,0 +1,5 @@
+// Subagent channel contract + implementation (types/readiness/channel split for one owner each).
+export * from "./types.js";
+export * from "./readiness.js";
+export * from "./channel.js";
+//# sourceMappingURL=index.js.map

package/lib/types/subagent/readiness.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChannelKind, ChannelState } from './types.ts';
+/** Pure derivation (no side effects): the doctor reads this, the channel re-probes on every run. */
+export declare function probeChannelState(ctx: Context, kind: ChannelKind): ChannelState;
+export declare function subagentChannelState(ctx: Context, kind: ChannelKind): ChannelState;
+//# sourceMappingURL=readiness.d.ts.map

package/lib/types/subagent/readiness.js

@@ -0,0 +1,35 @@
+import { restrictedPresetState } from "../composition/ensure.js";
+import { restrictedPresetId } from "../composition/preset-ids.js";
+function serviceOf(ctx, name) {
+    return ctx.get(name);
+}
+function kindOf(kind) {
+    return kind === 'reviewer' ? 'reviewer' : 'maintainer';
+}
+/** Pure derivation (no side effects): the doctor reads this, the channel re-probes on every run. */
+export function probeChannelState(ctx, kind) {
+    const subagents = serviceOf(ctx, 'subagents');
+    if (subagents === undefined || typeof subagents.getProvider !== 'function') {
+        return { kind: 'unavailable', code: 'E-323', reason: 'subagents service unavailable' };
+    }
+    const provider = subagents.getProvider('spawn');
+    if (provider === undefined)
+        return { kind: 'unavailable', code: 'E-323', reason: 'spawn provider unavailable' };
+    if (provider.capabilities?.agentPreset !== true) {
+        return { kind: 'unavailable', code: 'E-323', reason: 'spawn provider lacks the agentPreset capability' };
+    }
+    if (provider.inheritsParentContext === true) {
+        return { kind: 'unavailable', code: 'E-323', reason: 'spawn provider inherits the parent context (independent preset required)' };
+    }
+    const agentPresets = serviceOf(ctx, 'agentPresets');
+    if (agentPresets === undefined || typeof agentPresets.readDocument !== 'function' || typeof agentPresets.register !== 'function') {
+        return { kind: 'unavailable', code: 'E-323', reason: 'agentPresets service unavailable or incomplete' };
+    }
+    const id = restrictedPresetId(kindOf(kind));
+    const state = restrictedPresetState(ctx, kindOf(kind));
+    return { kind: 'available', provider: 'spawn', preset: { id, registered: state?.kind === 'ready' } };
+}
+export function subagentChannelState(ctx, kind) {
+    return probeChannelState(ctx, kind);
+}
+//# sourceMappingURL=readiness.js.map

package/lib/types/subagent/types.d.ts

@@ -0,0 +1,58 @@
+import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
+export type ChannelCode = 'E-323' | 'E-324';
+export type ChannelKind = 'reviewer' | 'maintainer';
+export interface PresetStatus {
+    readonly id: string;
+    readonly registered: boolean;
+    readonly broken?: string;
+}
+export type ChannelState = {
+    readonly kind: 'available';
+    readonly provider: 'spawn';
+    readonly preset: PresetStatus;
+} | {
+    readonly kind: 'unavailable';
+    readonly code: ChannelCode;
+    readonly reason: string;
+};
+export type ChannelOutcome<T = undefined> = {
+    readonly kind: 'ok';
+    readonly structured: unknown;
+    readonly childId: SessionId;
+    readonly stopReason: 'completed';
+    readonly evidence?: T;
+} | {
+    readonly kind: 'no-structured';
+    readonly childId?: SessionId;
+    readonly stopReason: SubagentStopReason;
+    readonly diagnostic?: string;
+    readonly evidence?: T;
+} | {
+    readonly kind: 'aborted';
+} | {
+    readonly kind: 'unavailable';
+    readonly code: ChannelCode;
+    readonly reason: string;
+};
+export interface ChannelSpec<T = undefined> {
+    readonly parent: Agent;
+    readonly label: string;
+    readonly promptText: string;
+    readonly kind: ChannelKind;
+    readonly allow: readonly string[];
+    readonly outputSchema?: ObjectJsonSchema;
+    readonly agentOptions?: AgentOptions;
+    readonly maxDepth?: number;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+    readonly afterResult?: (child: Agent) => T;
+}
+export interface SubagentChannel {
+    readonly state: ChannelState;
+    prepare(spec: Pick<ChannelSpec, 'kind' | 'allow'>): Promise<ChannelState>;
+    run<T = undefined>(spec: ChannelSpec<T>): Promise<ChannelOutcome<T>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/subagent/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map