@aiwayds/dsh-topics-memory 0.6.0 → 0.8.0

package/lib/index.js

@@ -6,6 +6,7 @@ import { buildTopicTools } from "./tools.js";
 import { buildTopicsCommand } from "./commands.js";
 import { Observer, textOf } from "./observer.js";
 import { Distiller, defaultModelCaller } from "./distill.js";
+import { SlowLane } from "./quality.js";
 import { CONFIG_KEYS, TopicsConfig } from "./config.js";
 import { isDelegated } from "./delegation.js";
 export const name = 'dsh-topics-memory';
@@ -167,12 +168,27 @@ export function apply(ctx) {
             const state = turns.get(sessionId);
             if (state === undefined)
                 return;
-            const dedup = cfgNow().injectDedup;
-            const seen = dedup ? injectedBySession.get(sessionId) : undefined;
-            const r = service.retrieveSync(query, sessionId, seen === undefined ? undefined : { exclude: seen });
-            // Mark only what entered the context this round (hits → dedup filter →
-            // assemble → registry mark; budget-dropped slugs stay injectable).
-            if (dedup && r.included.length > 0) {
+            const cfg = cfgNow();
+            const seen = cfg.injectDedup ? injectedBySession.get(sessionId) : undefined;
+            // Slow-lane consumption point (v4 生命周期表): the pending produced at
+            // the previous turn/end rides THIS splice — consumed or expired, the
+            // slot is gone either way (消费即清; expiry surfaces in record.why).
+            let slow;
+            let slowExpired;
+            if (cfg.autoInject) {
+                const consumed = slowLane.consume(sessionId, observer.turnCountOf(sessionId));
+                if (consumed !== undefined) {
+                    if ('pending' in consumed)
+                        slow = consumed.pending;
+                    else
+                        slowExpired = consumed.expired;
+                }
+            }
+            const r = service.retrieveSync(query, sessionId, seen === undefined ? undefined : { exclude: seen }, slow, slowExpired);
+            // Mark only what entered the context this round (hits AND slow picks →
+            // dedup filter → assemble → registry mark; budget-dropped slugs stay
+            // injectable).
+            if (cfg.injectDedup && (r.included.length > 0 || r.slowIncluded.length > 0)) {
                 let marked = injectedBySession.get(sessionId);
                 if (marked === undefined) {
                     marked = new Set();
@@ -180,6 +196,8 @@ export function apply(ctx) {
                 }
                 for (const slug of r.included)
                     marked.add(slug);
+                for (const slug of r.slowIncluded)
+                    marked.add(slug);
             }
             state.injectionText = r.text;
         }
@@ -187,6 +205,42 @@ export function apply(ctx) {
             // Contained: a retrieval failure must never break the turn.
         }
     }
+    /**
+     * Slow-lane production trigger at turn/end (v4 §4.2). Host-side gates live
+     * here: subagent sessions never run the lane (hard guard, independent of
+     * includeSubagents) and a distill run in flight makes the lane yield (the
+     * every-N-turns distill cadence shares this trigger).
+     */
+    function dispatchSlowLane(sessionId) {
+        try {
+            // Injection is off → the lane would burn aux LLM calls on pendings no
+            // spliced will ever consume (the spliced branch early-returns on
+            // autoInject before reaching the consume point).
+            if (!cfgNow().autoInject)
+                return;
+            if (isDelegated(agents()?.get(sessionId)))
+                return;
+            if (distiller.hasPending(sessionId))
+                return;
+            // Same trigger-time capture the distill trigger uses: the agent's
+            // scoped llm is alive NOW, and the lane's caller reads the captured
+            // entry lazily inside its async pipeline (released via the
+            // slowLane-aware guards once the pipeline settles).
+            try {
+                captureFromAgent(agents()?.get(sessionId));
+            }
+            catch {
+                // contained — the captured instance, if any, still walks the chain
+            }
+            slowLane.dispatch(sessionId, {
+                ring: observer.recentTurns(sessionId),
+                turnId: observer.turnCountOf(sessionId),
+            });
+        }
+        catch {
+            // contained — the lane must never break the event handler
+        }
+    }
     // ---- Tools ----
     const tools = ctx.tools;
     for (const tool of buildTopicTools(service))
@@ -229,6 +283,23 @@ export function apply(ctx) {
         return c.distillProvider !== '' && c.distillModel !== '' ? { provider: c.distillProvider, model: c.distillModel } : undefined;
     });
     const distiller = new Distiller(service, caller);
+    /**
+     * The ONE sessionLlm release decision, shared by every settle path (distill
+     * run settle, slow-lane pipeline settle, teardown, manual-distill decline):
+     * drop the captured entry only when no future read can need it. Keeping
+     * this in one place is what stopped the slow lane from re-opening the
+     * concern-1 leak (a disposal landing mid-pipeline must be closed out by
+     * the pipeline's own settle, not only by the one-shot disposal event).
+     */
+    const releaseSessionLlm = (sessionId) => {
+        if (!distiller.hasPending(sessionId) && !slowLane.hasInFlight(sessionId))
+            sessionLlm.delete(sessionId);
+    };
+    // Slow quality lane (v4 §4.2): shares the distill caller/route; owns its
+    // own pending lifecycle (produce at turn/end, consume at the next splice).
+    // The settle hook re-runs the release check because a disposal that landed
+    // mid-pipeline deferred to THIS pipeline and never fires again.
+    const slowLane = new SlowLane(service, caller, releaseSessionLlm);
     // ---- Observer (M2) ----
     // The process-exit disposer awaits this run (bounded): the callback below
     // records it synchronously when the fake 'dispose' session's end trigger
@@ -252,12 +323,7 @@ export function apply(ctx) {
         if (run !== undefined) {
             if (sessionId === 'dispose')
                 exitDistill = run;
-            void run
-                .finally(() => {
-                if (!distiller.hasPending(sessionId))
-                    sessionLlm.delete(sessionId);
-            })
-                .catch(() => undefined);
+            void run.finally(() => releaseSessionLlm(sessionId)).catch(() => undefined);
         }
     });
     // ---- Session events: injection + observation ----
@@ -337,8 +403,16 @@ export function apply(ctx) {
             // Restore/resume boundary: the persisted context is being replayed — a
             // fresh process has no dedup registry, so allow re-injection.
             injectedBySession.delete(sessionId);
+            slowLane.clear(sessionId);
         }
         observer.onSessionEvent(sessionId, event.type, event.data);
+        // AFTER the observer processed the turn (turnCount already bumped, so
+        // the pending stamps the correct turn id; the every-N distill trigger
+        // has already claimed its cadence slot — the lane yields to it inside
+        // dispatchSlowLane). The turns-map lifecycle above never touches the
+        // lane's pending map — the two coexist by design (v4 生命周期表).
+        if (event.type === 'turn/end')
+            dispatchSlowLane(sessionId);
     }));
     // ---- Session teardown: real cordis events, not session/event types ----
     // dsh-session 0.1.2-alpha.4's SessionEventMap has no `agent/disposed` or
@@ -363,12 +437,12 @@ export function apply(ctx) {
             captureFromAgent(subject.agent);
             observer.onSessionEvent(sessionId, name, undefined);
             injectedBySession.delete(sessionId);
+            slowLane.clear(sessionId);
             // A teardown-triggered run (session-end distill) reads the payload
             // capture lazily: drop the entry here only when no run can still read
-            // it. A pending run removes it on settle; a session that ends without
-            // any run must not leak its capture (long-running host process).
-            if (!distiller.hasPending(sessionId))
-                sessionLlm.delete(sessionId);
+            // it. The slow lane's in-flight pipeline reads it too (shared caller);
+            // its settle hook re-runs this check when the pipeline finishes.
+            releaseSessionLlm(sessionId);
         }));
     }
     // ---- Sync lifecycle: pull on session start, flush on dispose ----
@@ -465,16 +539,12 @@ export function apply(ctx) {
                 // capture above may have (re)armed the session's llm entry; with no
                 // run pending to consume-and-release it, drop it here — a declined
                 // request leaves no settle hook behind.
-                if (!distiller.hasPending(sessionId))
-                    sessionLlm.delete(sessionId);
+                releaseSessionLlm(sessionId);
                 return distiller.configured
                     ? { ok: false, reason: 'in-flight', created: [], updated: [], marked: 0 }
                     : { ok: false, reason: 'no-model', created: [], updated: [], marked: 0 };
             }
-            return run.finally(() => {
-                if (!distiller.hasPending(sessionId))
-                    sessionLlm.delete(sessionId);
-            });
+            return run.finally(() => releaseSessionLlm(sessionId));
         };
         cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate, resolveAsk, resolveLlm, manualDistill)), 'topics: /topics');
     });
@@ -489,10 +559,12 @@ const DEFAULTS = {
     totalBudget: 1500,
     matchThreshold: 0.3,
     tagBoost: 0.15,
+    injectMode: 'pointer',
+    qualityLane: 'sampled',
     graphDepth: 2,
     recencyWindowDays: 7,
     autoObserve: true,
-    includeSubagents: true,
+    includeSubagents: false,
     observationMaxChars: 2000,
     distillEveryTurns: 5,
     distillOnSessionEnd: true,

package/lib/observer.d.ts

@@ -16,6 +16,19 @@
  * @module observer
  */
 import type { TopicsService } from './service.ts';
+/** One completed turn in the ring buffer — the slow lane's only context source. */
+export interface RingEntry {
+    user: string;
+    assistant: string;
+    at: string;
+}
+/**
+ * Ring capacity (v4 §4.2 B1): the slow lane sees at most the last 3 completed
+ * turns. Deliberately small — query building wants the current intent, not a
+ * transcript; larger windows re-introduce the verbatim-priming surface the
+ * lane exists to remove.
+ */
+export declare const RING_CAPACITY = 3;
 export interface UserMessageLike {
     source?: {
         kind?: string;
@@ -34,6 +47,10 @@ export declare class Observer {
     private readonly onRequestDistill;
     constructor(service: TopicsService, onRequestDistill: (sessionId: string, reason: 'every-n' | 'session-end') => void);
     private stateFor;
+    /** Completed-turn snapshot for the slow lane (deep copy — callers may hold it). */
+    recentTurns(sessionId: string): RingEntry[];
+    /** Current turn count for the session (0 before the first turn ends). */
+    turnCountOf(sessionId: string): number;
     /** Entry point wired to ctx.on('session/event', …). */
     onSessionEvent(sessionId: string, eventType: string, data: unknown): void;
     private handleAsync;

package/lib/observer.js

@@ -15,6 +15,13 @@
  *
  * @module observer
  */
+/**
+ * Ring capacity (v4 §4.2 B1): the slow lane sees at most the last 3 completed
+ * turns. Deliberately small — query building wants the current intent, not a
+ * transcript; larger windows re-introduce the verbatim-priming surface the
+ * lane exists to remove.
+ */
+export const RING_CAPACITY = 3;
 export function textOf(message) {
     // Deliberately text-only and explicit: since dsh 0.1.2-alpha.3 sub-agent
     // follow-up messages may carry image (and other non-text) content blocks —
@@ -38,11 +45,19 @@ export class Observer {
     stateFor(sessionId) {
         let s = this.sessions.get(sessionId);
         if (s === undefined) {
-            s = { turnCount: 0, userText: '', assistantText: '', capturing: false };
+            s = { turnCount: 0, userText: '', assistantText: '', capturing: false, ring: [] };
             this.sessions.set(sessionId, s);
         }
         return s;
     }
+    /** Completed-turn snapshot for the slow lane (deep copy — callers may hold it). */
+    recentTurns(sessionId) {
+        return (this.sessions.get(sessionId)?.ring ?? []).map((e) => ({ ...e }));
+    }
+    /** Current turn count for the session (0 before the first turn ends). */
+    turnCountOf(sessionId) {
+        return this.sessions.get(sessionId)?.turnCount ?? 0;
+    }
     /** Entry point wired to ctx.on('session/event', …). */
     onSessionEvent(sessionId, eventType, data) {
         try {
@@ -72,8 +87,23 @@ export class Observer {
             }
             case 'turn/end': {
                 state.turnCount += 1;
+                // Cadence trigger FIRST and synchronously: index.ts dispatches the
+                // slow quality lane the moment onSessionEvent returns — which happens
+                // at the first await below (the observation write). The lane's
+                // distill-yield guard reads distiller.hasPending, so the every-N slot
+                // must be claimed before that first await or the %15 collision would
+                // never yield. The trigger's run fetches observations lazily; this
+                // turn's capture below still lands in the pool for a later run.
+                if (cfg.distillEveryTurns > 0 && state.turnCount % cfg.distillEveryTurns === 0) {
+                    this.onRequestDistill(sessionId, 'every-n');
+                }
                 const user = state.userText.trim();
                 const assistant = state.assistantText.trim();
+                if (user !== '' || assistant !== '') {
+                    state.ring.push({ user, assistant, at: new Date().toISOString() });
+                    if (state.ring.length > RING_CAPACITY)
+                        state.ring.splice(0, state.ring.length - RING_CAPACITY);
+                }
                 if (cfg.autoObserve && user !== '' && assistant !== '') {
                     await this.service.store.appendObservation({
                         kind: 'turn',
@@ -87,9 +117,6 @@ export class Observer {
                 }
                 state.userText = '';
                 state.assistantText = '';
-                if (cfg.distillEveryTurns > 0 && state.turnCount % cfg.distillEveryTurns === 0) {
-                    this.onRequestDistill(sessionId, 'every-n');
-                }
                 return;
             }
             // Real session teardown: both cordis events fire at teardown (agent

package/lib/okf.d.ts

@@ -30,6 +30,13 @@ export interface TopicFrontmatter {
     title: string;
     description?: string;
     tags: string[];
+    /**
+     * Self-declared recall triggers (v4 dual-channel design §4.1): short
+     * phrases that should recall this topic when they appear in a query.
+     * Optional; bundles written before the field simply have no trigger
+     * matching (degraded, never an error). Highest-weight strong field.
+     */
+    triggers?: string[];
     /** Bundle-relative paths: `topics/<slug>.md`. */
     depends: string[];
     open_questions: string[];

package/lib/okf.js

@@ -85,6 +85,15 @@ export function parseTopicDoc(raw) {
     };
     if (typeof fmRaw.description === 'string' && fmRaw.description !== '')
         fm.description = fmRaw.description;
+    // Triggers are producer-optional and must never invalidate an otherwise
+    // sound doc: non-string entries are filtered, not thrown (degrade, per the
+    // v4 design's "旧 bundle 无此字段降级不命中").
+    if (fmRaw.triggers !== undefined && fmRaw.triggers !== null) {
+        const raw = Array.isArray(fmRaw.triggers) ? fmRaw.triggers : [fmRaw.triggers];
+        const triggers = raw.filter((t) => typeof t === 'string' && t.trim() !== '').map((t) => t.trim());
+        if (triggers.length > 0)
+            fm.triggers = triggers;
+    }
     if ('verified' in fmRaw && fmRaw.verified !== null && fmRaw.verified !== undefined)
         fm.verified = asTrust(fmRaw.verified, 'verified');
     if (typeof fmRaw.stale_after === 'string' && fmRaw.stale_after !== '')
@@ -98,7 +107,7 @@ export function parseTopicDoc(raw) {
         });
     }
     // Preserve unknown producer-defined keys verbatim (OKF §4.1 extensions).
-    const known = new Set(['type', 'title', 'description', 'tags', 'depends', 'open_questions', 'impact', 'status', 'generated', 'verified', 'stale_after', 'sources']);
+    const known = new Set(['type', 'title', 'description', 'tags', 'triggers', 'depends', 'open_questions', 'impact', 'status', 'generated', 'verified', 'stale_after', 'sources']);
     for (const [k, v] of Object.entries(fmRaw)) {
         if (!known.has(k))
             fm[k] = v;
@@ -115,6 +124,8 @@ export function serializeTopicDoc(doc) {
     if (fm.description !== undefined)
         out.description = fm.description;
     out.tags = fm.tags;
+    if (fm.triggers !== undefined && fm.triggers.length > 0)
+        out.triggers = fm.triggers;
     out.depends = fm.depends;
     out.open_questions = fm.open_questions;
     out.impact = fm.impact;

package/lib/quality.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Slow quality lane (v4 dual-channel design §4.2) — asynchronous, turn-end
+ * triggered, LLM-gated injection. Two serial aux calls per run:
+ *
+ *   1. intent-query build over the observer's last-K ring buffer — kills
+ *      verbatim priming at the root (the query is what the model needs, not
+ *      what the user typed);
+ *   2. lexical candidate band (hits + near-misses, recall-oriented) then an
+ *      LLM rerank that releases 0-2 picks, each with a one-line why.
+ *
+ * Picks rest in a per-session pending slot and inject at the NEXT spliced
+ * (steer message), then the slot is gone (消费即清). Hard bounds: per-call
+ * 20s, pipeline 45s, pending TTL 10min, turn-lag ≤2. Every failure is
+ * contained and silent — I3 (可丢弃性): async products may be missing, never
+ * blocking. The lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
+ * records verdicts into ilog and never blocks a pick.
+ *
+ * @module quality
+ */
+import type { TopicsService } from './service.ts';
+import type { ModelCaller } from './distill.ts';
+import type { RingEntry } from './observer.ts';
+import type { QueryBuildShape } from './ilog.ts';
+export declare const PENDING_TTL_MS: number;
+/** Hard drift bound: a pending older than this many turn-ends expires. */
+export declare const TURN_LAG_LIMIT = 2;
+export declare const CALL_TIMEOUT_MS = 20000;
+export declare const PIPELINE_TIMEOUT_MS = 45000;
+/** qualityLane 'sampled' runs on every Nth turn (design default 1/3). */
+export declare const SAMPLED_EVERY = 3;
+export declare const QUERY_BUILD_PROMPT: string;
+export declare const RERANK_PROMPT: string;
+export interface PendingInjection {
+    items: {
+        slug: string;
+        why: string;
+    }[];
+    computedAt: string;
+    /** Observer turnCount when the pending was produced (turn-lag clock). */
+    turnId: number;
+    queryBuild: QueryBuildShape;
+    model: string;
+    ms: number;
+}
+export type ConsumeResult = {
+    pending: PendingInjection;
+} | {
+    expired: 'ttl' | 'turn-lag';
+} | undefined;
+export interface DispatchInput {
+    ring: readonly RingEntry[];
+    turnId: number;
+}
+/** Extract the first balanced JSON object from model output (tolerates fences). */
+export declare function parseJsonObject(raw: string): Record<string, unknown>;
+export declare class SlowLane {
+    private pending;
+    private inFlight;
+    private readonly service;
+    private readonly caller;
+    /**
+     * Settle hook: fires when a session's pipeline leaves the in-flight map.
+     * The host uses it to re-check the sessionLlm release guards — a disposal
+     * that landed mid-pipeline held the entry open for THIS pipeline, and this
+     * callback is the only chance to release it afterwards (the distill lane
+     * has the same shape via its run.finally).
+     */
+    private readonly onSettle;
+    constructor(service: TopicsService, caller: ModelCaller | undefined, onSettle?: (sessionId: string) => void);
+    /** True while the session has a pending slot awaiting the next spliced. */
+    hasPending(sessionId: string): boolean;
+    /** True while the session's produce pipeline is still running (llm-capture guard). */
+    hasInFlight(sessionId: string): boolean;
+    /** Drop the pending slot (session teardown, restore boundary). */
+    clear(sessionId: string): void;
+    /**
+     * Produce a pending slot for the session's next steer message. Fire-and-
+     * forget; every guard failure is silent. Policy gates live here (config,
+     * sampling, in-flight); host gates (delegation, distill yield) live with
+     * the caller, which owns those services.
+     */
+    dispatch(sessionId: string, input: DispatchInput): void;
+    private produce;
+    /**
+     * Consumption point (the next spliced). Returns the pending exactly once
+     * (消费即清) or an expiry reason; `turnId` is the CURRENT observer turn
+     * count so the drift bound can judge. Undefined when nothing is pending.
+     */
+    consume(sessionId: string, turnId: number): ConsumeResult;
+}