@elvisw/dsh-magic-context 0.0.0-stage → 0.13.0

package/lib/dsh/search-hint.js

@@ -0,0 +1,186 @@
+/**
+ * Auto-search hint — proactive recall (upstream `auto-search-hint.ts` +
+ * `auto-search-runner.ts`).
+ *
+ * When a new user turn arrives, optionally search this project's memories with the
+ * user's OWN words and append a short "you may recall something related" entry to
+ * the session stream. The hint deliberately fragments and compresses: the goal is
+ * to nudge the agent into running its memory search for full context, not to hand
+ * it the answer. Guardrails are upstream's: ≤3 fragments, ~80 chars each, ≤800
+ * chars total.
+ *
+ * Two deliberate differences from upstream:
+ *
+ * - **Carrier.** Upstream appends the hint to the user message itself; the
+ *   adapter never edits the user's text (one durable surface, and the title
+ *   derives from the first `source: 'user'` message). The hint instead travels
+ *   as its own user-role message INSIDE the admitted batch: `planSearchHint`
+ *   returns the built message and the pre-step listener appends it to
+ *   `decision.messages`, which the host persists verbatim after its own
+ *   system-prompt commits (host agent-loop `step()`: system commits first, then
+ *   `for (const message of decision.messages) session.append('user/message',
+ *   message)`). That ordering is the fix for the 2026-10-09 corruption
+ *   incident: the previous carrier appended directly from inside the
+ *   `agent/pre-step` waterfall, which on a fresh session's first step ran
+ *   BEFORE the host wrote `step/start` and the first `system/message`, making
+ *   the hint surface node 0 — the loader's `foldSurface` then rejected the log
+ *   on every replay ("requires a protected first surface head"; 10/10 corrupt
+ *   logs had the hint as the early node). Inside the batch, the host's own
+ *   commits always precede the hint, the hint still rides the request it was
+ *   computed for (the request is built from the surface after the batch lands),
+ *   and the transcript renders the same collapsed `source.kind` row as before.
+ * - **FTS-only search.** `lane.searchForSession` skips the embedding request, so a
+ *   cold local model cannot delay the turn the hint is meant to inform. The
+ *   stored-vector lane remains available to `ctx_memory` (`action:"search"`),
+ *   where the agent asked for it.
+ *
+ * Fail-open everywhere: a hint is an optimisation, and no turn may fail over it.
+ */
+import { randomUUID } from 'node:crypto';
+import { magicContextSource } from "./seams.js";
+/** Upstream's limits (auto-search-hint.ts). */
+export const HINT_MAX_FRAGMENTS = 3;
+export const HINT_FRAGMENT_CHARS = 80;
+export const HINT_MAX_CHARS = 800;
+/** Upstream's deadline is 3s; local FTS is milliseconds, so this is a backstop. */
+export const HINT_TIMEOUT_MS = 2_000;
+function truncate(text, limit) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    return normalized.length <= limit ? normalized : `${normalized.slice(0, Math.max(0, limit - 1)).trimEnd()}…`;
+}
+/**
+ * Render the hint entry, or null when there is nothing worth saying.
+ * @param hits - ranked memory hits from the FTS lane.
+ * @param options - fragment count and per-fragment character cap.
+ * @returns the `<ctx-search-hint>` block, bounded by {@link HINT_MAX_CHARS}.
+ */
+export function buildSearchHint(hits, options = {}) {
+    const maxFragments = Math.max(1, options.maxFragments ?? HINT_MAX_FRAGMENTS);
+    const fragmentChars = Math.max(20, options.fragmentChars ?? HINT_FRAGMENT_CHARS);
+    const lines = hits
+        .slice(0, maxFragments)
+        .map(hit => truncate(`[${hit.category}] ${hit.preview}`, fragmentChars))
+        .filter(fragment => fragment.length > 0);
+    if (lines.length === 0)
+        return null;
+    const header = lines.length === 1
+        ? 'Your memory may contain 1 related fragment:'
+        : `Your memory may contain ${String(lines.length)} related fragments:`;
+    const footer = 'If the fragments above seem relevant to the current request, you may run ctx_memory '
+        + 'with action "search" to retrieve full context. Otherwise ignore.';
+    const body = [header, ...lines.map(line => `- ${line}`), footer].join('\n');
+    const wrapped = `<ctx-search-hint>\n${body}\n</ctx-search-hint>`;
+    if (wrapped.length <= HINT_MAX_CHARS)
+        return wrapped;
+    const overflow = wrapped.length - HINT_MAX_CHARS;
+    const trimmed = body.slice(0, Math.max(0, body.length - overflow - 1)).trimEnd();
+    return `<ctx-search-hint>\n${trimmed}…\n</ctx-search-hint>`;
+}
+/**
+ * One hint per user turn. preStep runs once per model request, so a turn with
+ * tool calls would otherwise append the same hint at every step.
+ */
+export class SearchHintTracker {
+    turns = new Map();
+    /**
+     * Claim the right to hint for one turn.
+     * @param sessionId - the session the turn belongs to.
+     * @param turnKey - the newest user message id (stable across this turn's steps).
+     * @returns true when this turn has not been hinted yet.
+     */
+    claim(sessionId, turnKey) {
+        if (this.turns.get(sessionId) === turnKey)
+            return false;
+        this.turns.set(sessionId, turnKey);
+        if (this.turns.size > 64) {
+            const oldest = this.turns.keys().next().value;
+            if (oldest !== undefined)
+                this.turns.delete(oldest);
+        }
+        return true;
+    }
+    /** Forget a session (its hints restart from scratch). */
+    forget(sessionId) {
+        this.turns.delete(sessionId);
+    }
+}
+/** Bound a promise so a slow search can never hold the turn. */
+async function withDeadline(work, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise(resolve => {
+                timer = setTimeout(() => { resolve(undefined); }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Build the hint's durable message: the exact shape the direct-append carrier
+ * used (`appendMagicContextEntry`), now delivered inside the admitted batch.
+ * Structural, not host-typed on purpose: the host persists batch messages
+ * verbatim (`session.append('user/message', message)`), so the producer source
+ * round-trips without a declared kind in the host's `MessageSourceMap`.
+ */
+export function buildHintMessage(hint, hits) {
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: hint }],
+        source: magicContextSource(`Magic Context · ${String(hits)} possible memory match(es) — ctx_memory (action "search") for full context`),
+    };
+}
+/**
+ * Decide whether this turn gets a hint, and build its message when it does.
+ * The caller carries the message inside `decision.messages` — the hint never
+ * appends to the session directly from here (protected-head incident,
+ * 2026-10-09; see the carrier note in the header).
+ *
+ * Every outcome is journaled as `search-hint` so the thresholds can be tuned from
+ * telemetry rather than guessed at.
+ * @param deps - the search closure, journal, and knobs.
+ * @param input - the user's text and this turn's key.
+ * @returns what happened, for callers that want to log or assert.
+ */
+export async function planSearchHint(deps, input) {
+    const now = deps.now ?? Date.now;
+    const record = (outcome, detail = {}) => {
+        deps.journal?.info('search-hint', `auto-search hint: ${outcome.action === 'quiet' ? outcome.reason : outcome.action}`, { action: outcome.action, ...'reason' in outcome ? { reason: outcome.reason } : {}, ...detail, trigger: 'pre-step' }, input.sessionId);
+        return outcome;
+    };
+    if (deps.search === undefined)
+        return record({ action: 'quiet', reason: 'lane-off' });
+    const text = input.text.trim();
+    const minChars = deps.minChars ?? 24;
+    // A command or one of our own hints is never a prompt, however short: the
+    // length gate below must not answer for them.
+    if (text.startsWith('/') || text.includes('<ctx-search-hint>')) {
+        return record({ action: 'quiet', reason: 'not-a-prompt' });
+    }
+    if (text.length < minChars)
+        return record({ action: 'quiet', reason: 'too-short' }, { chars: text.length });
+    if (deps.tracker !== undefined && !deps.tracker.claim(input.sessionId, input.turnKey)) {
+        return record({ action: 'quiet', reason: 'already-hinted' });
+    }
+    const queries = text.slice(0, 400);
+    const started = now();
+    let hits;
+    try {
+        const found = await withDeadline(deps.search(input.session, queries, deps.limit ?? 5), deps.timeoutMs ?? HINT_TIMEOUT_MS);
+        if (found === undefined)
+            return record({ action: 'failed', reason: 'timeout' }, { ms: now() - started });
+        hits = found;
+    }
+    catch (error) {
+        return record({ action: 'failed', reason: 'search-failed' }, { detail: error instanceof Error ? error.message : String(error) });
+    }
+    const hint = buildSearchHint(hits);
+    if (hint === null)
+        return record({ action: 'quiet', reason: 'no-hits' }, { ms: now() - started });
+    return record({ action: 'hinted', hits: hits.length, text: hint, message: buildHintMessage(hint, hits.length) }, { ms: now() - started, chars: hint.length });
+}

package/lib/dsh/session-notice.js

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { magicContextSource } from "./seams.js";
+/** The host's one-line bound for `notice` summaries. */
+export const NOTICE_SUMMARY_MAX_CHARS = 120;
+function boundSummary(summary) {
+    return summary.length <= NOTICE_SUMMARY_MAX_CHARS
+        ? summary
+        : `${summary.slice(0, NOTICE_SUMMARY_MAX_CHARS - 1)}…`;
+}
+function grouped(n) {
+    return n.toLocaleString('en-US');
+}
+/** `1 compartment` / `2 compartments`; the notice carries no plural-rule table. */
+function plural(count, one, many) {
+    return count === 1 ? one : many;
+}
+/**
+ * The one-line account of a pass, or null when nothing notable happened.
+ * Baseline-only refreshes (a negative token delta with no discrete action)
+ * stay quiet: an execute pass runs every step while pressure is high and a
+ * notice per step would spam the transcript.
+ */
+export function sessionNoticeSummary(result) {
+    const parts = [];
+    const delta = result.tokensAfter - result.tokensBefore;
+    if (result.forceDropped > 0) {
+        parts.push(`emergency-dropped ${grouped(result.forceDropped)} `
+            + plural(result.forceDropped, 'tool output', 'tool outputs'));
+    }
+    if (result.published.length > 0) {
+        parts.push(`compacted ${grouped(result.published.length)} `
+            + plural(result.published.length, 'compartment', 'compartments')
+            + ` ${result.published.map(id => `§C${String(id)}§`).join(' ')}`
+            + (delta < 0 ? ` · reclaimed ${grouped(-delta)} tok` : ''));
+    }
+    else if (delta < 0 && result.forceDropped > 0) {
+        parts.push(`reclaimed ${grouped(-delta)} tok`);
+    }
+    if (result.factsPromoted > 0) {
+        parts.push(`promoted ${grouped(result.factsPromoted)} `
+            + plural(result.factsPromoted, 'memory', 'memories')
+            + (result.factsSeenAgain > 0 ? ` (${grouped(result.factsSeenAgain)} already known)` : ''));
+    }
+    if (parts.length === 0)
+        return null;
+    return boundSummary(`Magic Context · ${parts.join(' · ')}`);
+}
+/**
+ * Append one magic-context entry to the live stream. The single home of the entry
+ * shape: a user-role message carrying the plugin source, appended with
+ * `surfaceOp: 'append'` so the host accepts it as a normal tail node.
+ *
+ * Refuses on a headless surface: an out-of-band append before the host has
+ * written surface node 0 (the first `system/message`) would take that position
+ * itself and make the log unloadable on replay (2026-10-09 incident; the class
+ * rule lives in {@link SessionNoticeSession}).
+ *
+ * Never throws: a broken transcript nicety must not wedge the turn.
+ * @param session - the session whose stream is appended to.
+ * @param text - the model-visible body (keep it short; it becomes context).
+ * @param summary - the one-line collapsed row the transcript shows.
+ * @returns the appended seq, or the refusal/append failure.
+ */
+export function appendMagicContextEntry(session, text, summary) {
+    if (session.surface !== undefined && session.surface.nodes.length === 0) {
+        return { ok: false, reason: 'headless-surface' };
+    }
+    const message = {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source: magicContextSource(boundSummary(summary)),
+    };
+    try {
+        return { ok: true, seq: session.append('user/message', message, { surfaceOp: 'append' }) };
+    }
+    catch (error) {
+        return { ok: false, reason: 'append-failed', detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Append one notice entry for a management pass outcome. Never throws: a
+ * broken transcript nicety must not wedge the turn (fail-open, like every
+ * other best-effort surface in the adapter).
+ */
+export function appendSessionNotice(input) {
+    const summary = sessionNoticeSummary(input.result);
+    if (summary === null)
+        return { ok: false, reason: 'not-notable' };
+    const lines = [summary];
+    if (input.result.baselineUpdated)
+        lines.push('Baseline refreshed (m[0] frozen point advanced)');
+    const appended = appendMagicContextEntry(input.session, lines.join('\n'), summary);
+    if (!appended.ok) {
+        return appended.reason === 'headless-surface'
+            ? { ok: false, reason: 'headless-surface' }
+            : { ok: false, reason: 'append-failed', detail: appended.detail };
+    }
+    return { ok: true, summary, seq: appended.seq };
+}

package/lib/dsh/status-command.js

@@ -0,0 +1,75 @@
+import { decidePass, pressurePercent, pressureWindowTokens } from "../core/policy.js";
+import { enumerateSurfaceToolResults, requestContextOf } from "./seams.js";
+export function registerCtxStatusCommand(ctx, deps) {
+    const commands = ctx.get('commands');
+    if (commands === undefined) {
+        ctx.logger.warn('magic-context dsh adapter: commands service not mounted; /ctx-status unavailable');
+        return;
+    }
+    commands.register({
+        name: 'ctx-status',
+        description: 'Magic Context: pressure, reclaim ledger, and pass state for this session.',
+        handler: (invocation) => {
+            const sessionId = invocation.agent.session.id;
+            const policy = typeof deps.policy === 'function' ? deps.policy() : deps.policy;
+            const latest = deps.stores.latestUsage(sessionId);
+            const { contextWindow } = requestContextOf(invocation.agent.session);
+            // The same denominator the pass decision uses, so the reported percent
+            // and the decision printed below it can never disagree.
+            const pressureWindow = pressureWindowTokens(contextWindow, policy);
+            const pressure = pressurePercent(latest, pressureWindow);
+            const decision = decidePass({ latest, pressure, now: Date.now(), policy });
+            const nodes = enumerateSurfaceToolResults(invocation.agent.session, callId => deps.stores.getTag(sessionId, { kind: 'tool-result', callId }));
+            const tagged = nodes.filter(node => node.tagNumber !== undefined);
+            const dropped = tagged.filter(node => node.isPlaceholder);
+            const pending = deps.stores.listPendingDrops(sessionId);
+            const compartments = deps.stores.listCompartments(sessionId);
+            const unlanded = deps.stores.listUnlandedCompartments(sessionId);
+            const baseline = deps.stores.baselineState(sessionId);
+            const coveredTokens = compartments.reduce((total, compartment) => total + compartment.coveredTokens, 0);
+            // Journal health: the validation-period at-a-glance check (the full
+            // review lives in scripts/mc-report.mjs).
+            let journalLine = '- journal: unavailable';
+            try {
+                const bounds = deps.stores.journalBounds();
+                const dayAgo = Date.now() - 24 * 60 * 60_000;
+                const recent = deps.stores.journalByKind(dayAgo);
+                const errors = recent.filter(row => row.level === 'error').reduce((total, row) => total + row.count, 0);
+                const passes = recent.filter(row => row.kind === 'pass').reduce((total, row) => total + row.count, 0);
+                journalLine = `- journal: ${String(bounds.rows)} entries`
+                    + `${bounds.newest === undefined ? '' : `, latest ${new Date(bounds.newest).toISOString()}`}`
+                    + `; last 24h: ${String(passes)} pass event(s), ${String(errors)} error(s)`
+                    + `${bounds.rows === 0 ? ' (audit layer empty: was this build reloaded?)' : ''}`;
+            }
+            catch (error) {
+                journalLine = `- journal: read failed (${error instanceof Error ? error.message : String(error)})`;
+            }
+            const lines = [
+                'Magic Context (dsh adapter) — status',
+                `- usage: ${latest === undefined
+                    ? 'no response recorded yet'
+                    : `${pressure === undefined ? '?' : pressure.toFixed(1)}% of ${String(pressureWindow)} tokens`
+                        + `${contextWindow === undefined ? ' (assumed; the route discloses none)' : ''} `
+                        + `(last input ${String(latest.inputTokens ?? 0)} + cache `
+                        + `${String((latest.cacheReadTokens ?? 0) + (latest.cacheWriteTokens ?? 0))}, `
+                        + `at ${new Date(latest.recordedAt).toISOString()})`}`,
+                `- pass: ${decision.kind} (${decision.reason})`,
+                `- tool outputs: ${String(tagged.length)} tagged, ${String(dropped.length)} dropped as placeholders`,
+                `- reclaim queue: ${pending.length === 0 ? 'empty' : pending.map(tag => `§${String(tag)}§`).join(', ')}`,
+                `- historian: ${String(compartments.length)} compartment(s), ~${String(coveredTokens)} tokens digested`
+                    + `${unlanded.length === 0 ? '' : `, ${String(unlanded.length)} awaiting publication`}`,
+                `- baseline: ${baseline === undefined
+                    ? 'not built yet'
+                    : `epoch ${String(baseline.epoch)}, node ${String(baseline.nodeSeq ?? '?')}, `
+                        + `frozen ${new Date(baseline.frozenAt).toISOString()}`
+                        + `${baseline.memoriesDigest === undefined ? '' : ', memories injected'}`}`,
+                `- policy: execute ≥ ${String(policy.executeThreshold)}%, force ≥ ${String(policy.forceThreshold)}%, `
+                    + `ttl ${String(Math.round(policy.ttlMs / 1000))}s, protect newest ${String(policy.protectedToolResults)} `
+                    + `(+${String(policy.historianProtectedNodes)} from the historian), `
+                    + `assumed window ${String(policy.assumedContextWindow)} tokens`,
+                journalLine,
+            ];
+            return { kind: 'success', text: lines.join('\n') };
+        },
+    });
+}