@evomap/evolver-core 2.0.0-beta.0

package/dist/hooks/hooks.d.ts

@@ -0,0 +1,117 @@
+import { type ExtractedSignal, type SignalSourceTurn } from '../signals/extractor.js';
+import { type ValueSummary } from '../ops/index.js';
+export interface SessionStartConfig {
+    tokenBudgetHardCap: number;
+    injectGenes?: readonly string[];
+    preamble?: string;
+    /** Value-outreach recap line (#113): quiet metadata about injected memory/value context. Higher priority than
+     *  the gene-list tail — when over budget the gene tail is cut FIRST and the recap is kept, so the agent keeps
+     *  the context even in a tight budget. Empty/absent → no recap, no behavior change. */
+    recap?: string;
+}
+export interface SessionStartInjection {
+    systemPrompt: string;
+    tokenBudget: number;
+    genes: string[];
+    /** Whether the recap line survived into the prompt (false only if it was absent). */
+    recapIncluded: boolean;
+}
+/**
+ * 构造 SessionStart 注入. token 预算钉在 hard cap, 注入内容超额则截断 gene 列表(预算优先).
+ * Priority order (#113): preamble + recap are kept; only the GENE list is trimmed from its tail to fit the cap.
+ * The recap is a fixed quiet-context line, so it sits above every gene in priority — a tight budget drops genes,
+ * never the recap. The recap is assembled with the preamble (both retained as one head block).
+ */
+export declare function buildSessionStartInjection(cfg: SessionStartConfig, estimateTokens?: (s: string) => number): SessionStartInjection;
+/** Inputs the SessionStart recap (#113) needs from real run state: the genes being injected, the past successes
+ *  they were learned from, and the value summary for the recap window. */
+export interface SessionStartRecapContext {
+    /** Genes selected for this session's injection (N) — the rendered lines that go into the prompt. */
+    injectGenes: readonly string[];
+    /**
+     * Stable gene IDs aligned POSITIONALLY with `injectGenes` (line[i] ↔ id[i]), for inject attribution (#123).
+     * When present, the inject emission reports these IDs (mapped to the survivors of the budget trim) so the
+     * value ledger attributes by a stable id, not a rendered line. When absent, the emission falls back to the
+     * surviving line strings. Length should match `injectGenes`; a shorter array contributes no id past its end.
+     */
+    geneIds?: readonly string[];
+    /** Past successes the injected genes were distilled from (M) — e.g. distinct solidified cycles. */
+    successCount?: number;
+    /** Value summary for the recap window (its measured total is X). */
+    summary: ValueSummary;
+}
+/**
+ * What the SessionStart inject emission seam (#123) reports — the value-ledger attribution anchors for a
+ * `value.inject` root_event. This is an ATTRIBUTION-ONLY signal (the weakest in the ledger): it records WHICH
+ * genes were actually injected (and, when known, the session outcome) and carries NO savings number. The genes
+ * reported are the ones that survived the hard-cap budget trim — i.e. the genes the agent really saw, not the
+ * pre-trim candidate list.
+ */
+export interface InjectInfo {
+    /** The gene ids actually injected into the prompt (post budget-trim). */
+    geneIds: readonly string[];
+    /** The cycle this injection feeds, when there is one. */
+    cycleId?: string;
+    /**
+     * The runtime's session id, when the hook delivers it (Claude Code passes it on SessionStart stdin). Recorded so
+     * a later attribution pass (recall) can tie THIS inject to the exact session transcript it produced (#205),
+     * instead of guessing "the most recent inject". Absent for runtimes that expose no per-session id (e.g. cursor).
+     */
+    sessionId?: string;
+    /**
+     * Session outcome, when observable. At SessionStart the session has not run yet, so this is normally absent;
+     * the field exists so a later attribution pass can carry it. Never scored into a number (attribution only).
+     */
+    outcome?: string;
+}
+/** Options for the recap-composing SessionStart injection (#123): the optional inject emission seam. */
+export interface ComposeSessionStartOptions {
+    /** Token estimator (defaults to the char/4 heuristic inside buildSessionStartInjection). */
+    estimateTokens?: (s: string) => number;
+    /**
+     * Inject emission seam (#123). Fired exactly once with the genes that ACTUALLY made it into the prompt (after
+     * the hard-cap trim) so the value ledger can derive a source=inject record. Core stays sink-agnostic: the
+     * composition layer wires this to a `value.inject` root_event. Best-effort + MUST NOT throw — injection is the
+     * agent's critical path, so an emission error can never be allowed to break or delay it (fire-and-forget,
+     * mirroring the reuse-hit seam). Not fired when nothing was injected (no genes survived the budget).
+     */
+    onInject?: (info: InjectInfo) => void;
+    /** The cycle this injection feeds — carried into onInject so the event refs the SAME cycleId as the cycle. */
+    cycleId?: string;
+    /** The runtime session id — carried into onInject so the value.inject event can be tied back to its session (#205). */
+    sessionId?: string;
+}
+/**
+ * Compose a SessionStart injection WITH a value-outreach recap (#113), end to end. This is the real integration
+ * seam: it derives a quiet context line from live run state (N injected genes, M past successes, X measured
+ * tokens saved — all from the passed summary + counts, never invented) and threads it through the same hard-cap
+ * budget as `buildSessionStartInjection`, where the recap outranks the gene tail. The recap is omitted (no line
+ * added) when there is nothing honest to say. Pure given its inputs (+ the injected token estimator).
+ *
+ * Inject emission (#123): when an `onInject` seam is wired (via the options object form of the third argument),
+ * it fires ONCE with the genes that actually survived the budget trim (`inj.genes`) so the value ledger can feed
+ * its source=inject rail with REAL data. The emission is best-effort and fire-and-forget: a thrown error from the
+ * seam is swallowed and never propagates, so an attribution side-effect can never break the agent's injection.
+ *
+ * The third argument is overloaded for back-compat: a bare function is the token estimator (the original
+ * signature); an options object carries the estimator plus the optional inject seam.
+ */
+export declare function composeSessionStartWithRecap(base: Omit<SessionStartConfig, 'recap'>, recapCtx: SessionStartRecapContext, estimateTokensOrOpts?: ((s: string) => number) | ComposeSessionStartOptions): SessionStartInjection;
+export interface ToolUseEvent {
+    toolName: string;
+    toolResult?: string;
+    isError?: boolean;
+    text?: string;
+}
+/** PostToolUse 钩子: 把一次 tool 调用结果转成信号(复用三条腿提取). */
+export declare function signalsFromToolUse(event: ToolUseEvent): ExtractedSignal[];
+export interface StopMemoryEntry {
+    kind: 'session_summary';
+    summary: string;
+    signalCount: number;
+    signals: string[];
+    outcome: 'productive' | 'idle';
+    ts: number;
+}
+/** Stop 钩子: 把本 session 的信号沉淀成一条 memory(批注#6). idle(无信号)也记, 但标 idle. */
+export declare function buildStopMemory(turns: readonly SignalSourceTurn[], now: number): StopMemoryEntry;

package/dist/hooks/hooks.js

@@ -0,0 +1,89 @@
+import { extractSignals } from '../signals/extractor.js';
+import { buildValueRecap } from '../ops/index.js';
+/**
+ * 构造 SessionStart 注入. token 预算钉在 hard cap, 注入内容超额则截断 gene 列表(预算优先).
+ * Priority order (#113): preamble + recap are kept; only the GENE list is trimmed from its tail to fit the cap.
+ * The recap is a fixed quiet-context line, so it sits above every gene in priority — a tight budget drops genes,
+ * never the recap. The recap is assembled with the preamble (both retained as one head block).
+ */
+export function buildSessionStartInjection(cfg, estimateTokens = (s) => Math.ceil(s.length / 4)) {
+    const genes = [...(cfg.injectGenes ?? [])];
+    const recap = (cfg.recap ?? '').trim();
+    // The head block (preamble + recap) is never trimmed — only the gene tail is.
+    const head = [cfg.preamble ?? '', recap].filter(Boolean);
+    const compose = () => [...head, ...genes].filter(Boolean).join('\n');
+    let prompt = compose();
+    // hard cap: 注入超预算就从尾部砍 gene(保 preamble + recap, 预算优先且 recap 优先级高于 gene 尾部)
+    while (genes.length > 0 && estimateTokens(prompt) > cfg.tokenBudgetHardCap) {
+        genes.pop();
+        prompt = compose();
+    }
+    return { systemPrompt: prompt, tokenBudget: cfg.tokenBudgetHardCap, genes, recapIncluded: recap.length > 0 };
+}
+/**
+ * Compose a SessionStart injection WITH a value-outreach recap (#113), end to end. This is the real integration
+ * seam: it derives a quiet context line from live run state (N injected genes, M past successes, X measured
+ * tokens saved — all from the passed summary + counts, never invented) and threads it through the same hard-cap
+ * budget as `buildSessionStartInjection`, where the recap outranks the gene tail. The recap is omitted (no line
+ * added) when there is nothing honest to say. Pure given its inputs (+ the injected token estimator).
+ *
+ * Inject emission (#123): when an `onInject` seam is wired (via the options object form of the third argument),
+ * it fires ONCE with the genes that actually survived the budget trim (`inj.genes`) so the value ledger can feed
+ * its source=inject rail with REAL data. The emission is best-effort and fire-and-forget: a thrown error from the
+ * seam is swallowed and never propagates, so an attribution side-effect can never break the agent's injection.
+ *
+ * The third argument is overloaded for back-compat: a bare function is the token estimator (the original
+ * signature); an options object carries the estimator plus the optional inject seam.
+ */
+export function composeSessionStartWithRecap(base, recapCtx, estimateTokensOrOpts) {
+    const opts = typeof estimateTokensOrOpts === 'function' ? { estimateTokens: estimateTokensOrOpts } : (estimateTokensOrOpts ?? {});
+    const recap = buildValueRecap({
+        injectedCount: recapCtx.injectGenes.length,
+        ...(recapCtx.successCount !== undefined ? { successCount: recapCtx.successCount } : {}),
+        summary: recapCtx.summary,
+    });
+    const inj = buildSessionStartInjection({ ...base, injectGenes: recapCtx.injectGenes, recap }, opts.estimateTokens);
+    // Inject emission (#123): record the genes that ACTUALLY landed in the prompt (post budget-trim), not the
+    // pre-trim candidate list — the ledger should attribute only what the agent really saw. The trim drops from the
+    // TAIL, so the survivors are the FIRST inj.genes.length entries; map them to the aligned stable gene ids (when
+    // provided) so attribution is by id, not by a rendered line. Fire-and-forget: skip when nothing was injected,
+    // and never let a seam error escape into the injection path.
+    if (opts.onInject && inj.genes.length > 0) {
+        const geneIds = recapCtx.geneIds
+            ? recapCtx.geneIds.slice(0, inj.genes.length).filter((id) => typeof id === 'string')
+            : inj.genes;
+        if (geneIds.length > 0) {
+            try {
+                opts.onInject({
+                    geneIds,
+                    ...(opts.cycleId ? { cycleId: opts.cycleId } : {}),
+                    ...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+                });
+            }
+            catch { /* emission must never break the injection path */ }
+        }
+    }
+    return inj;
+}
+/** PostToolUse 钩子: 把一次 tool 调用结果转成信号(复用三条腿提取). */
+export function signalsFromToolUse(event) {
+    const turn = {
+        toolName: event.toolName,
+        ...(event.isError && event.toolResult ? { errorMessage: event.toolResult } : {}),
+        ...(event.text ? { text: event.text } : {}),
+        isMeta: false,
+    };
+    return extractSignals([turn]);
+}
+/** Stop 钩子: 把本 session 的信号沉淀成一条 memory(批注#6). idle(无信号)也记, 但标 idle. */
+export function buildStopMemory(turns, now) {
+    const signals = extractSignals(turns);
+    return {
+        kind: 'session_summary',
+        summary: signals.length > 0 ? `${signals.length} 个信号: ${signals.slice(0, 3).map((s) => s.kind).join(', ')}` : '无信号 session',
+        signalCount: signals.length,
+        signals: signals.slice(0, 20).map((s) => s.text.slice(0, 120)),
+        outcome: signals.length > 0 ? 'productive' : 'idle',
+        ts: now,
+    };
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './hooks.js';

package/dist/hooks/index.js

@@ -0,0 +1 @@
+export * from './hooks.js';

package/dist/hub/assetCallLog.d.ts

@@ -0,0 +1,43 @@
+export type AssetCallAction = 'hub_search_hit' | 'hub_search_miss' | 'asset_reuse' | 'asset_reference' | 'asset_publish' | 'asset_publish_skip' | 'hub_review_submitted' | 'hub_review_rejected' | 'hub_review_failed';
+export interface AssetCallEntry {
+    run_id?: string | null;
+    action: AssetCallAction;
+    asset_id?: string;
+    asset_type?: string;
+    source_node_id?: string;
+    chain_id?: string;
+    score?: number;
+    mode?: 'direct' | 'reference';
+    signals?: readonly string[];
+    reason?: string;
+    extra?: Record<string, unknown>;
+}
+export interface AssetCallRecord extends AssetCallEntry {
+    timestamp: string;
+}
+export interface ReadOpts {
+    run_id?: string;
+    action?: AssetCallAction;
+    /** Only entries at/after this ISO time. */
+    since?: string;
+    /** Only the last N entries (after the other filters). */
+    last?: number;
+}
+export interface CallLogSummary {
+    total_entries: number;
+    unique_assets: number;
+    unique_runs: number;
+    by_action: Record<string, number>;
+    entries: AssetCallRecord[];
+}
+export declare class AssetCallLog {
+    private readonly path;
+    private readonly now;
+    constructor(path: string, now?: () => Date);
+    /** Append one record (timestamped). Never throws — logging must not break evolution. */
+    append(entry: AssetCallEntry): void;
+    /** Read records with optional filters. Corrupt lines are skipped. */
+    read(opts?: ReadOpts): AssetCallRecord[];
+    /** Totals + per-action counts (for CLI / observability). */
+    summarize(opts?: ReadOpts): CallLogSummary;
+}

package/dist/hub/assetCallLog.js

@@ -0,0 +1,72 @@
+// Append-only asset-call log (ported from v1 gep/assetCallLog.js). Records every hub-asset interaction across
+// evolution runs — search hits/misses, reuse/reference, publish, and review outcomes — as one JSONL line each.
+// This is the audit trail behind "which fetched assets actually got reused, and did the reuse pay off"; the
+// reuse-reward / quality-feedback loops read it. Best-effort by construction: a logging failure NEVER blocks
+// or fails an evolution. The log path is injected so it's testable without a real home dir.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class AssetCallLog {
+    path;
+    now;
+    constructor(path, now = () => new Date()) {
+        this.path = path;
+        this.now = now;
+    }
+    /** Append one record (timestamped). Never throws — logging must not break evolution. */
+    append(entry) {
+        if (!entry || typeof entry !== 'object')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const record = { timestamp: this.now().toISOString(), ...entry };
+            appendFileSync(this.path, `${JSON.stringify(record)}\n`, 'utf8');
+        }
+        catch { /* non-fatal */ }
+    }
+    /** Read records with optional filters. Corrupt lines are skipped. */
+    read(opts = {}) {
+        if (!existsSync(this.path))
+            return [];
+        let entries = [];
+        try {
+            for (const line of readFileSync(this.path, 'utf8').split('\n')) {
+                if (!line)
+                    continue;
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch { /* skip corrupt */ }
+            }
+        }
+        catch {
+            return [];
+        }
+        if (opts.since) {
+            const sinceTs = new Date(opts.since).getTime();
+            if (Number.isFinite(sinceTs))
+                entries = entries.filter((e) => new Date(e.timestamp).getTime() >= sinceTs);
+        }
+        if (opts.run_id)
+            entries = entries.filter((e) => e.run_id === opts.run_id);
+        if (opts.action)
+            entries = entries.filter((e) => e.action === opts.action);
+        if (opts.last && Number.isFinite(opts.last) && opts.last > 0)
+            entries = entries.slice(-opts.last);
+        return entries;
+    }
+    /** Totals + per-action counts (for CLI / observability). */
+    summarize(opts = {}) {
+        const entries = this.read(opts);
+        const byAction = {};
+        const assets = new Set();
+        const runs = new Set();
+        for (const e of entries) {
+            byAction[e.action] = (byAction[e.action] ?? 0) + 1;
+            if (e.asset_id)
+                assets.add(e.asset_id);
+            if (e.run_id)
+                runs.add(e.run_id);
+        }
+        return { total_entries: entries.length, unique_assets: assets.size, unique_runs: runs.size, by_action: byAction, entries };
+    }
+}

package/dist/hub/bindings.d.ts

@@ -0,0 +1,28 @@
+import type { HubCapability, HubBindings } from './capability.js';
+import { type LeakCheckMode } from './sanitize.js';
+/** publish 回执非 accepted → 抛此错; SyncEngine 据 terminal 决定是否重试. */
+export declare class PublishRejectedError extends Error {
+    readonly status: string;
+    readonly terminal: boolean;
+    readonly retryAfterMs?: number | undefined;
+    readonly retryable?: boolean | undefined;
+    constructor(status: string, terminal: boolean, reason?: string, retryAfterMs?: number | undefined, retryable?: boolean | undefined);
+}
+/** makeHubBindings options. Pre-publish sanitize is on by default (both public + private adapters share this single chokepoint). */
+export interface HubBindingsOptions {
+    sanitize?: {
+        /** Default true: deep-redact + leak-scan before egress. Off = raw publish (tests / special cases only). */
+        enabled?: boolean;
+        /** Source for the env reverse-scan + EVOLVER_LEAK_CHECK. Defaults to process.env. */
+        env?: Record<string, string | undefined>;
+        /** Override the leak-check mode (strict = refuse / warn = log only / off = skip scan). Defaults to reading env, which defaults to strict. */
+        mode?: LeakCheckMode;
+    };
+}
+/**
+ * 把 HubCapability 接到 core 两 seam(M6-1):
+ * - asProxyHandler: Dispatcher.handlers.proxy — 按 envelope.type 路由到 hub. 抛错→store.fail()重试;
+ *   但 publish 终态(reject/quarantine/402)抛 PublishRejectedError{terminal:true}, 调用方据此不重试(money-safety).
+ * - asAssetTransport: assetstore RemoteTransport — 落库前 core normalizeForPut, 不信任远端 asset_id.
+ */
+export declare function makeHubBindings(cap: HubCapability, options?: HubBindingsOptions): HubBindings;

package/dist/hub/bindings.js

@@ -0,0 +1,90 @@
+import { normalizeForPut } from '../assetstore/provider.js';
+import { sanitizeBundle, summarizeLeaks } from './sanitize.js';
+/** publish 回执非 accepted → 抛此错; SyncEngine 据 terminal 决定是否重试. */
+export class PublishRejectedError extends Error {
+    status;
+    terminal;
+    retryAfterMs;
+    retryable;
+    constructor(status, terminal, reason, retryAfterMs, retryable) {
+        super(`publish ${status}${reason ? `: ${reason}` : ''}`);
+        this.status = status;
+        this.terminal = terminal;
+        this.retryAfterMs = retryAfterMs;
+        this.retryable = retryable;
+        this.name = 'PublishRejectedError';
+    }
+}
+function envelopeToAgentEvent(e) {
+    const stableId = e.type === 'proxy_trace' && e.idempotencyKey ? e.idempotencyKey : e.id;
+    return {
+        id: stableId,
+        type: e.type,
+        payload: e.payload,
+        priority: 'medium',
+        createdAt: e.createdAt,
+        ...(e.type === 'proxy_trace' && e.idempotencyKey ? { refId: e.idempotencyKey } : {}),
+    };
+}
+/**
+ * 把 HubCapability 接到 core 两 seam(M6-1):
+ * - asProxyHandler: Dispatcher.handlers.proxy — 按 envelope.type 路由到 hub. 抛错→store.fail()重试;
+ *   但 publish 终态(reject/quarantine/402)抛 PublishRejectedError{terminal:true}, 调用方据此不重试(money-safety).
+ * - asAssetTransport: assetstore RemoteTransport — 落库前 core normalizeForPut, 不信任远端 asset_id.
+ */
+export function makeHubBindings(cap, options = {}) {
+    const sanCfg = options.sanitize ?? {};
+    const sanEnabled = sanCfg.enabled ?? true;
+    const sanEnv = sanCfg.env ?? (typeof process !== 'undefined' ? process.env : {});
+    /** Single publish chokepoint: sanitize (on by default) → strict + leak found → refuse (terminal, not retryable) → cap.publish the redacted bundle. */
+    const publishSanitized = (bundle) => {
+        if (!sanEnabled)
+            return cap.publish(bundle);
+        const r = sanitizeBundle(bundle, { env: sanEnv, ...(sanCfg.mode ? { mode: sanCfg.mode } : {}) });
+        if (r.blocked) {
+            throw new PublishRejectedError('leak_blocked', true, `sensitive data detected before publish, refused (not retryable): ${summarizeLeaks(r.leaks)}`);
+        }
+        return cap.publish(r.bundle);
+    };
+    return {
+        asProxyHandler() {
+            return async (e) => {
+                switch (e.type) {
+                    case 'asset_submit': {
+                        // payload 可为 bundle {assets:[...]} 或单资产; 统一成 bundle 数组发.
+                        const p = e.payload;
+                        const bundle = Array.isArray(p.assets) ? p.assets : [p];
+                        const r = await publishSanitized(bundle);
+                        if (r.status !== 'accepted')
+                            throw new PublishRejectedError(r.status, r.terminal ?? true, r.reason);
+                        return r;
+                    }
+                    case 'task_claim': return cap.task.claim(String(e.payload.taskId ?? ''));
+                    case 'task_complete': {
+                        const p = e.payload;
+                        return cap.task.complete(String(p.claimId ?? ''), p.result);
+                    }
+                    default:
+                        // 其余 outbound(atp_*/heartbeat/...) 走 mailbox.push
+                        await cap.mailbox.push(envelopeToAgentEvent(e));
+                        return { pushed: true };
+                }
+            };
+        },
+        asAssetTransport() {
+            return {
+                putRemote: async (record) => {
+                    const { record: clean } = normalizeForPut(record); // 不信任远端 asset_id, core 侧重算
+                    const r = await publishSanitized([clean]); // 单资产传输也走 bundle API([asset]) + 发布前脱敏
+                    return { stored: r.status === 'accepted' };
+                },
+                getRemote: async (assetId) => {
+                    const got = await cap.fetch({ limit: 10000 });
+                    return got.find((a) => a.asset_id === assetId) ?? null;
+                },
+                searchRemote: (query) => cap.search(query),
+                listRemote: (kind, limit) => cap.fetch({ ...(kind ? { kind } : {}), limit }),
+            };
+        },
+    };
+}