@aiwayds/dsh-topics-memory 0.6.0

package/lib/git.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Git CLI wrapper for the bundle Cache (ADR 0002/0003).
+ *
+ * Every command is an argv-array child process (no shell), with a timeout and
+ * a plugin identity for commits (`user.name`/`user.email` via -c, never
+ * touching the user's git config). In GitHub mode the token is attached
+ * per-invocation as an http.extraHeader — it never lands in the remote URL,
+ * .git/config, or any file (ADR 0002).
+ *
+ * @module git
+ */
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare class GitError extends Error {
+    name: string;
+    readonly result: GitResult;
+    constructor(message: string, result: GitResult);
+}
+export interface GitRunOptions {
+    cwd: string;
+    timeoutMs?: number;
+    /** Token for http extra header (push/pull in GitHub mode). */
+    token?: string;
+    /** Throw GitError on non-zero exit (default true). */
+    mayFail?: boolean;
+}
+export declare function runGit(args: readonly string[], opts: GitRunOptions): Promise<GitResult>;
+export declare function isRepo(cwd: string): Promise<boolean>;
+export declare function initRepo(cwd: string, branch?: string): Promise<void>;
+export declare function addAndCommit(cwd: string, paths: readonly string[], message: string): Promise<boolean>;
+export declare function headRev(cwd: string): Promise<string | undefined>;
+export interface HistoryEntry {
+    hash: string;
+    date: string;
+    message: string;
+}
+/** Per-file history — the toolized exit of 「git 可追溯」(need 3). */
+export declare function fileHistory(cwd: string, path: string, limit?: number): Promise<HistoryEntry[]>;
+/** The full content of a topic file at a given revision (conclusion diffing). */
+export declare function fileAtRev(cwd: string, path: string, rev: string): Promise<string | undefined>;
+export interface PullOutcome {
+    ok: boolean;
+    /** Paths left in conflicted state (empty when ok). */
+    conflicted: string[];
+    output: string;
+}
+/**
+ * `pull --rebase` with conflict containment: on conflict we abort the rebase
+ * (ADR 0003 — no automatic smart merging) and report the conflicted paths so
+ * the caller can mark those topics. Remote and branch are explicit — the
+ * bundle never depends on upstream tracking config.
+ */
+export declare function pullRebase(cwd: string, token?: string, remote?: string, branch?: string): Promise<PullOutcome>;
+export declare function push(cwd: string, token?: string, remote?: string, branch?: string): Promise<{
+    ok: boolean;
+    output: string;
+}>;
+export declare function setRemote(cwd: string, url: string, remote?: string): Promise<void>;
+export declare function removeRemote(cwd: string, remote?: string): Promise<void>;
+export declare function hasRemote(cwd: string, remote?: string): Promise<boolean>;
+export declare function unpushedCount(cwd: string, remote?: string, branch?: string): Promise<number>;
+/** True when the remote advertises the branch — empty remotes skip the pull step. */
+export declare function remoteBranchExists(cwd: string, token?: string, remote?: string, branch?: string): Promise<boolean>;

package/lib/git.js

@@ -0,0 +1,169 @@
+/**
+ * Git CLI wrapper for the bundle Cache (ADR 0002/0003).
+ *
+ * Every command is an argv-array child process (no shell), with a timeout and
+ * a plugin identity for commits (`user.name`/`user.email` via -c, never
+ * touching the user's git config). In GitHub mode the token is attached
+ * per-invocation as an http.extraHeader — it never lands in the remote URL,
+ * .git/config, or any file (ADR 0002).
+ *
+ * @module git
+ */
+import { spawn } from 'node:child_process';
+export class GitError extends Error {
+    name = 'GitError';
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+export function runGit(args, opts) {
+    const extra = [];
+    if (opts.token !== undefined && opts.token !== '') {
+        const basic = Buffer.from(`x-access-token:${opts.token}`, 'utf8').toString('base64');
+        extra.push('-c', `http.extraHeader=Authorization: Basic ${basic}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', [...extra, ...args], {
+            cwd: opts.cwd,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new GitError(`git ${args[0]} timed out after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`, { code: -1, stdout, stderr }));
+        }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        child.stdout.on('data', (d) => {
+            stdout += d.toString('utf8');
+        });
+        child.stderr.on('data', (d) => {
+            stderr += d.toString('utf8');
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const result = { code: code ?? -1, stdout, stderr };
+            if ((code ?? -1) !== 0 && opts.mayFail !== true) {
+                reject(new GitError(`git ${args[0]} failed (${code}): ${stderr.trim().split('\n').at(-1) ?? ''}`, result));
+            }
+            else {
+                resolve(result);
+            }
+        });
+    });
+}
+/** Commit identity so bundle history never depends on the machine's git config. */
+const IDENTITY = ['-c', 'user.name=dsh-topics-memory', '-c', 'user.email=dsh-topics-memory@localhost'];
+export async function isRepo(cwd) {
+    const r = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd, mayFail: true }).catch(() => undefined);
+    return r !== undefined && r.code === 0 && r.stdout.trim() === 'true';
+}
+export async function initRepo(cwd, branch = 'main') {
+    await runGit(['init', '-b', branch], { cwd });
+}
+export async function addAndCommit(cwd, paths, message) {
+    await runGit(['add', '--', ...paths], { cwd });
+    // Commit only when something is staged (write-through must not spam empty commits).
+    const staged = await runGit(['diff', '--cached', '--name-only'], { cwd });
+    if (staged.stdout.trim() === '')
+        return false;
+    const r = await runGit([...IDENTITY, 'commit', '-m', message], { cwd });
+    return r.code === 0;
+}
+export async function headRev(cwd) {
+    const r = await runGit(['rev-parse', 'HEAD'], { cwd, mayFail: true }).catch(() => undefined);
+    if (r === undefined || r.code !== 0)
+        return undefined;
+    return r.stdout.trim();
+}
+/** Per-file history — the toolized exit of 「git 可追溯」(need 3). */
+export async function fileHistory(cwd, path, limit = 50) {
+    const r = await runGit(['log', '--follow', `--max-count=${limit}`, '--date=iso-strict', '--pretty=%H%x09%ad%x09%s', '--', path], { cwd, mayFail: true }).catch(() => undefined);
+    if (r === undefined || r.code !== 0)
+        return [];
+    return r.stdout
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [hash, date, ...rest] = l.split('\t');
+        return { hash: hash ?? '', date: date ?? '', message: rest.join('\t') };
+    });
+}
+/** The full content of a topic file at a given revision (conclusion diffing). */
+export async function fileAtRev(cwd, path, rev) {
+    const r = await runGit(['show', `${rev}:${path}`], { cwd, mayFail: true }).catch(() => undefined);
+    if (r === undefined || r.code !== 0)
+        return undefined;
+    return r.stdout;
+}
+/**
+ * `pull --rebase` with conflict containment: on conflict we abort the rebase
+ * (ADR 0003 — no automatic smart merging) and report the conflicted paths so
+ * the caller can mark those topics. Remote and branch are explicit — the
+ * bundle never depends on upstream tracking config.
+ */
+export async function pullRebase(cwd, token, remote = 'origin', branch = 'main') {
+    const r = await runGit(['pull', '--rebase', '--autostash', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
+        return { code: -1, stdout: '', stderr: String(e instanceof Error ? e.message : e) };
+    });
+    if (r.code === 0)
+        return { ok: true, conflicted: [], output: r.stdout + r.stderr };
+    const conflicted = (await runGit(['diff', '--name-only', '--diff-filter=U'], { cwd, mayFail: true }).catch(() => ({ code: -1, stdout: '', stderr: '' }))).stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '');
+    if (conflicted.length > 0) {
+        await runGit(['rebase', '--abort'], { cwd, mayFail: true }).catch(() => undefined);
+    }
+    return { ok: false, conflicted, output: r.stdout + r.stderr };
+}
+export async function push(cwd, token, remote = 'origin', branch = 'main') {
+    const r = await runGit(['push', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
+        return { code: -1, stdout: '', stderr: String(e instanceof Error ? e.message : e) };
+    });
+    return { ok: r.code === 0, output: (r.stdout + r.stderr).trim() };
+}
+export async function setRemote(cwd, url, remote = 'origin') {
+    const existing = await runGit(['remote', 'get-url', remote], { cwd, mayFail: true }).catch(() => undefined);
+    if (existing !== undefined && existing.code === 0 && existing.stdout.trim() !== '') {
+        await runGit(['remote', 'set-url', remote, url], { cwd });
+    }
+    else {
+        await runGit(['remote', 'add', remote, url], { cwd });
+    }
+}
+export async function removeRemote(cwd, remote = 'origin') {
+    await runGit(['remote', 'remove', remote], { cwd, mayFail: true }).catch(() => undefined);
+}
+export async function hasRemote(cwd, remote = 'origin') {
+    const r = await runGit(['remote', 'get-url', remote], { cwd, mayFail: true }).catch(() => undefined);
+    return r !== undefined && r.code === 0 && r.stdout.trim() !== '';
+}
+export async function unpushedCount(cwd, remote = 'origin', branch = 'main') {
+    const r = await runGit(['rev-list', '--count', `${remote}/${branch}..${branch}`], { cwd, mayFail: true }).catch(() => undefined);
+    if (r === undefined || r.code !== 0)
+        return 0;
+    return Number(r.stdout.trim()) || 0;
+}
+/** True when the remote advertises the branch — empty remotes skip the pull step. */
+export async function remoteBranchExists(cwd, token, remote = 'origin', branch = 'main') {
+    const r = await runGit(['ls-remote', '--heads', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch(() => undefined);
+    return r !== undefined && r.code === 0 && r.stdout.trim() !== '';
+}

package/lib/ilog.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Injection log (ADR 0007) — one record per retrieval round, no conversation
+ * text, only features and decisions. Aggregations power `/topics stats` and the
+ * near-miss evidence that makes threshold tuning measurable.
+ *
+ * @module ilog
+ */
+export interface InjectionRecord {
+    at: string;
+    sessionId?: string;
+    /** Query shape: token count and a bounded sample (features, not content). */
+    queryTokenCount: number;
+    querySample?: string;
+    rosterSize: number;
+    hits: {
+        slug: string;
+        score: number;
+        reasons: string[];
+        viaGraph: boolean;
+    }[];
+    nearMisses: {
+        slug: string;
+        score: number;
+    }[];
+    injected: boolean;
+    why?: string;
+    dropped?: {
+        slug: string;
+        reason: string;
+    }[];
+    /** Slugs blocked this round by session-level injection dedup (never assembled). */
+    deduped?: string[];
+    usedTokens?: number;
+}
+export interface AggregateStats {
+    rounds: number;
+    injectedRounds: number;
+    hitRate: number;
+    zeroHitRounds: number;
+    avgHitsPerRound: number;
+    topTopics: {
+        slug: string;
+        count: number;
+    }[];
+    nearMissHistogram: {
+        bucket: string;
+        count: number;
+    }[];
+    avgBudgetUtilization: number;
+}
+export declare function aggregateStats(records: readonly InjectionRecord[]): AggregateStats;
+/** Bounded sample of the query kept for debugging — words only, max 40 chars. */
+export declare function querySample(query: string): string;

package/lib/ilog.js

@@ -0,0 +1,70 @@
+/**
+ * Injection log (ADR 0007) — one record per retrieval round, no conversation
+ * text, only features and decisions. Aggregations power `/topics stats` and the
+ * near-miss evidence that makes threshold tuning measurable.
+ *
+ * @module ilog
+ */
+export function aggregateStats(records) {
+    const rounds = records.length;
+    let injectedRounds = 0;
+    let zeroHitRounds = 0;
+    let hitsSum = 0;
+    let budgetSamples = 0;
+    let budgetSum = 0;
+    const topicCounts = new Map();
+    const buckets = new Map();
+    for (const r of records) {
+        if (r.injected)
+            injectedRounds += 1;
+        if (r.hits.length === 0)
+            zeroHitRounds += 1;
+        hitsSum += r.hits.length;
+        if (typeof r.usedTokens === 'number' && r.usedTokens > 0) {
+            budgetSamples += 1;
+            budgetSum += r.usedTokens;
+        }
+        // topTopics feeds 「Top-N 被注入 Topic」— deduped hits were NOT injected,
+        // so they must not inflate the per-slug injection counts. Retrieval-shape
+        // metrics above (hits/rounds, zero-hit rounds) keep counting raw hits.
+        const deduped = r.deduped === undefined ? undefined : new Set(r.deduped);
+        for (const h of r.hits) {
+            if (deduped?.has(h.slug))
+                continue;
+            topicCounts.set(h.slug, (topicCounts.get(h.slug) ?? 0) + 1);
+        }
+        for (const nm of r.nearMisses) {
+            const bucket = nmBucket(nm.score);
+            buckets.set(bucket, (buckets.get(bucket) ?? 0) + 1);
+        }
+    }
+    const topTopics = [...topicCounts.entries()]
+        .map(([slug, count]) => ({ slug, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+    const nearMissHistogram = [...buckets.entries()]
+        .sort((a, b) => bucketOrder(a[0]) - bucketOrder(b[0]))
+        .map(([bucket, count]) => ({ bucket, count }));
+    return {
+        rounds,
+        injectedRounds,
+        hitRate: rounds === 0 ? 0 : Math.round((injectedRounds / rounds) * 1000) / 1000,
+        zeroHitRounds,
+        avgHitsPerRound: rounds === 0 ? 0 : Math.round((hitsSum / rounds) * 100) / 100,
+        topTopics,
+        nearMissHistogram,
+        avgBudgetUtilization: budgetSamples === 0 ? 0 : Math.round((budgetSum / budgetSamples) * 100) / 100,
+    };
+}
+function nmBucket(score) {
+    const floor = Math.floor(score * 20) / 20;
+    return `${floor.toFixed(2)}–${(floor + 0.05).toFixed(2)}`;
+}
+function bucketOrder(label) {
+    return Number(label.split('–')[0]);
+}
+/** Bounded sample of the query kept for debugging — words only, max 40 chars. */
+export function querySample(query) {
+    const words = query.replace(/\s+/g, ' ').trim();
+    return words.length <= 40 ? words : `${words.slice(0, 40)}…`;
+}

package/lib/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * dsh-topics-memory — OKF topic memory for DeepSeek Harness.
+ *
+ * Wiring (per ADR 0001–0008):
+ *  - `topics` settings namespace (user-tunable via /topics set)
+ *  - static systemPrompt section teaching the topic tools (never volatile
+ *    content — the provider cache prefix stays byte-stable)
+ *  - same-turn injection: retrieval runs synchronously at inbox-claim time
+ *    (`agent/inbox/spliced` live event, which dispatches BEFORE prompt
+ *    assembly — the only seam early enough, per the dsh-llmwiki upstream's
+ *    validated recipe) and a systemPrompt.context() provider serves the assembled
+ *    digest for this turn
+ *  - model tools: topic_save / topic_search / topic_observe / topic_history
+ *  - `/topics` command via the shared dsh-commands registry (optional peer)
+ *  - observer (M2): turn capture + distill triggers over session events
+ *  - sync (ADR 0003): pull on session start, debounced write-through push
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-topics-memory";
+/**
+ * Bounded wait for the process-exit distill. Session teardown is the last
+ * distill trigger, but the disposer used to fire it fire-and-forget — process
+ * exit always won the race and the run died unwritten. The disposer now waits
+ * for the run, capped so a pathological (hanging) model call can never wedge
+ * the host's exit.
+ */
+export declare const EXIT_DISTILL_TIMEOUT_MS = 90000;
+/**
+ * Resolve when `p` settles (rejection swallowed) or after `ms`, whichever
+ * comes first. The cap timer is unref'd: an otherwise-idle event loop exits
+ * naturally instead of being kept alive purely by the bound.
+ */
+export declare function settleBounded(p: Promise<unknown> | undefined, ms: number): Promise<void>;
+/** Services consumed at apply time; llm joins via guarded ctx.inject. */
+export declare const inject: string[];
+/**
+ * Settings-provider surface the legacy-namespace migration needs. Structurally
+ * typed like every other host seam in this file, so bare test harnesses
+ * without dsh-settings still load the module: a host lacking `describe` or
+ * `mutate` simply skips the migration.
+ */
+interface SettingsNsLike {
+    register(n: unknown, s: unknown): {
+        get(): unknown;
+    };
+    describe?(): {
+        ns: unknown;
+        user?: unknown;
+    }[];
+    mutate?(ns: unknown, ops: readonly {
+        op: 'set';
+        path: string[];
+        value?: unknown;
+    }[]): Promise<void>;
+}
+/**
+ * One-time carry-over of user-tuned values from the pre-rename `llmwiki`
+ * settings namespace into `topics` (ADR 0013). Constraints:
+ * - one-time: only fires while the new namespace holds NO raw user overrides —
+ *   describe().user is the only way to tell user keys from schema defaults,
+ *   because scope.get() folds the defaults in;
+ * - idempotent: after the copy (or any config written on the new name) the
+ *   override check short-circuits every later boot;
+ * - fail-open: registering the legacy namespace can throw (duplicate or
+ *   schema-invalid stored section) and the write can reject — both contained,
+ *   so plugin startup never depends on the migration.
+ * Keys whose stored value equals the schema default are not copied (nothing
+ * user-tuned to preserve). Returns the in-flight write for tests; apply()
+ * fire-and-forgets it.
+ */
+export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (message: string) => void): Promise<void> | undefined;
+export declare function apply(ctx: Context): void;
+export {};