@elvisw/dsh-magic-context 0.0.0-bootstrap.0

package/lib/dsh/config.js

@@ -0,0 +1,13 @@
+/**
+ * Legacy `tags.retentionDays` detector. The schema no longer declares `tags`,
+ * but schemastery preserves undeclared keys, so an old profile can still carry
+ * the block. It is data, not a setting: return a warning only when a value is
+ * present, never for an absent or empty block. The mount path owns the
+ * once-per-process latch.
+ */
+export function legacyTagsRetentionWarning(config) {
+    const legacy = config.tags;
+    if (legacy?.retentionDays === undefined)
+        return undefined;
+    return 'magic-context dsh adapter: tags.retentionDays is deprecated and ignored; tag rows are no longer pruned by age. Remove the tags block from the profile.';
+}

package/lib/dsh/context-pressure.js

@@ -0,0 +1,36 @@
+/**
+ * When a context-pressure reading is worth a journal row.
+ *
+ * The host's `contextPressure` projection changes on nearly every step, and the
+ * listener used to journal every distinct reading: measured at ~10 rows/minute
+ * during heavy work (2,516 rows on 2026-10-07, 413 rows in 44 minutes on
+ * 2026-10-08). The gauge only needs a reading that is genuinely new, so a
+ * reading is logged when it is at least {@link CONTEXT_PRESSURE_MIN_DELTA_TOKENS}
+ * or {@link CONTEXT_PRESSURE_MIN_DELTA_RATIO} of the window away from the last
+ * LOGGED one — plus whenever the window itself changes, and always for the
+ * first reading of a session.
+ *
+ * The panel reads the newest row, so the visible cost is a gauge that may lag
+ * by up to that threshold (≤0.25% of the window); the benefit is a journal
+ * whose pressure history is readable instead of a wall of near-identical rows.
+ */
+/** Absolute floor: below this, a change is noise regardless of window size. */
+export const CONTEXT_PRESSURE_MIN_DELTA_TOKENS = 512;
+/** Relative gate: keeps the threshold meaningful on very large windows. */
+export const CONTEXT_PRESSURE_MIN_DELTA_RATIO = 0.0025;
+/** The tokens the gauge would show: the projection's own preference order. */
+export function pressureUsedTokens(reading) {
+    return reading.projectedTokens ?? reading.pressureTokens ?? 0;
+}
+export function shouldLogContextPressure(previous, reading) {
+    const used = pressureUsedTokens(reading);
+    const window = reading.contextWindow ?? 0;
+    // The first reading of a session is always worth a row (it anchors the gauge).
+    if (previous === undefined)
+        return true;
+    // A changed window is a different measurement, not a small movement.
+    if (window !== previous.window)
+        return true;
+    const delta = Math.abs(used - previous.used);
+    return delta >= Math.max(CONTEXT_PRESSURE_MIN_DELTA_TOKENS, Math.round(window * CONTEXT_PRESSURE_MIN_DELTA_RATIO));
+}

package/lib/dsh/drop-landing.js

@@ -0,0 +1,42 @@
+import { estimateTokensFromLength } from "../core/compartments.js";
+import { dropPlaceholderContent, enumerateSurfaceToolResults, replaceToolResultContent, } from "./seams.js";
+export function landPendingDrops(input) {
+    const wanted = [...new Set(input.tags)];
+    if (wanted.length === 0)
+        return { landed: [], already: [], skipped: [] };
+    const toolNodes = enumerateSurfaceToolResults(input.session, callId => input.stores.getTag(input.sessionId, { kind: 'tool-result', callId }));
+    const landed = [];
+    const already = [];
+    const skipped = [];
+    // Capture the original length BEFORE replacement: after
+    // `replaceToolResultContent` the node is the placeholder, so a
+    // post-replacement scan estimates 0 tokens for every landed row. The
+    // `SurfaceToolNode` already carries `textLength`, so no extra surface walk
+    // is needed (the old code walked the whole surface after replacing).
+    const originalLength = new Map();
+    for (const tag of wanted) {
+        const node = toolNodes.find(candidate => candidate.tagNumber === tag);
+        if (node === undefined) {
+            skipped.push(tag);
+            continue;
+        }
+        if (node.isPlaceholder) {
+            input.stores.markDropLanded(input.sessionId, tag, node.seq);
+            already.push(tag);
+            continue;
+        }
+        originalLength.set(tag, node.textLength);
+        const landedSeq = replaceToolResultContent(input.session, node.seq, dropPlaceholderContent(tag));
+        input.onReplaced?.(tag);
+        input.stores.markDropLanded(input.sessionId, tag, landedSeq);
+        landed.push(tag);
+    }
+    if (landed.length > 0) {
+        input.journal?.info('drop-landed', `landed ${String(landed.length)} drop(s): ${landed.map(tag => `§${String(tag)}§`).join(', ')}`, {
+            tags: landed,
+            count: landed.length,
+            estTokens: landed.reduce((total, tag) => total + estimateTokensFromLength(originalLength.get(tag) ?? 0), 0),
+        }, input.sessionId);
+    }
+    return { landed, already, skipped };
+}

package/lib/dsh/emergency.js

@@ -0,0 +1,89 @@
+import { dropPlaceholderContent, replaceToolResultContent } from "./seams.js";
+/** MC emergency-drop.ts:54-55 — T1 keeps longest, T2 medium, T3 default. */
+const T1_TOOLS = new Set(['read', 'todowrite', 'task']);
+const T2_TOOLS = new Set(['edit', 'write', 'apply_patch', 'grep', 'glob']);
+/** MC normalizeToolName: lowercase; strip the `mcp_` provider prefix. */
+export function normalizeToolName(toolName) {
+    const lowered = (toolName ?? '').toLowerCase().trim();
+    return lowered.startsWith('mcp_') ? lowered.slice(4) : lowered;
+}
+export function resolveToolTier(toolName) {
+    const name = normalizeToolName(toolName);
+    if (T1_TOOLS.has(name))
+        return 1;
+    if (T2_TOOLS.has(name))
+        return 2;
+    return 3;
+}
+/** clamp(contextWindow × 5%, 8k, 64k) — undefined when the window is unknown. */
+export function protectionWindowTokens(contextWindow) {
+    if (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) {
+        return undefined;
+    }
+    return Math.min(64_000, Math.max(8_000, Math.round(contextWindow * 0.05)));
+}
+/** MC's token estimate for a text length in characters (≈4 chars/token). */
+function tokensFor(textLength) {
+    return Math.ceil(textLength / 4);
+}
+/**
+ * Drop reclaimable tool results. A node is reclaimable when it carries an
+ * adapter tag, is not already a placeholder, and sits outside the protected
+ * window: the newest results whose cumulative estimate fits the token window,
+ * plus at least the newest `policy.protectedToolResults` tagged nodes.
+ */
+export function reclaimForEmergency(session, nodes, policy, contextWindow, 
+/** #731: whole-surface token estimate (all nodes); without it the guard is off. */
+surfaceTokensEstimate) {
+    const tagged = nodes.filter(node => node.tagNumber !== undefined && !node.isPlaceholder);
+    const windowTokens = protectionWindowTokens(contextWindow);
+    // Walk newest → oldest: inside the token window, or within the count floor,
+    // a node is protected; the first node past both bounds ends the window.
+    const protectedSeqs = new Set();
+    let protectedTokens = 0;
+    for (let index = tagged.length - 1; index >= 0; index -= 1) {
+        const node = tagged[index];
+        const cost = tokensFor(node.textLength);
+        const withinWindow = windowTokens !== undefined && protectedTokens + cost <= windowTokens;
+        if (withinWindow || tagged.length - 1 - index < policy.protectedToolResults) {
+            protectedSeqs.add(node.seq);
+            protectedTokens += cost;
+            continue;
+        }
+        break;
+    }
+    // Drop order: worst tier first, oldest first inside a tier.
+    const reclaimable = tagged
+        .filter(node => !protectedSeqs.has(node.seq))
+        .sort((left, right) => resolveToolTier(right.toolName ?? null) - resolveToolTier(left.toolName ?? null)
+        || left.seq - right.seq);
+    // #731: if everything reclaimable vanished and the request STILL would not
+    // fit, the drop cannot fix the overflow — preserve the results (upstream:
+    // `Rewriting tools cannot fix oversized fixed overhead`).
+    if (contextWindow !== undefined && surfaceTokensEstimate !== undefined) {
+        const reclaimableTokens = reclaimable.reduce((total, node) => total + tokensFor(node.textLength), 0);
+        const residualTokens = surfaceTokensEstimate - reclaimableTokens;
+        if (residualTokens > contextWindow) {
+            return {
+                dropped: [],
+                protectedCount: tagged.length - reclaimable.length,
+                ...windowTokens === undefined ? {} : { protectedTokens },
+                skipped: 'cannot-fit',
+                residualTokens,
+            };
+        }
+    }
+    const dropped = [];
+    for (const node of reclaimable) {
+        const tagNumber = node.tagNumber;
+        if (tagNumber === undefined)
+            continue;
+        replaceToolResultContent(session, node.seq, dropPlaceholderContent(tagNumber));
+        dropped.push({ seq: node.seq, tagNumber });
+    }
+    return {
+        dropped,
+        protectedCount: tagged.length - reclaimable.length,
+        ...windowTokens === undefined ? {} : { protectedTokens },
+    };
+}

package/lib/dsh/flush-command.js

@@ -0,0 +1,148 @@
+import { errText } from "../core/types.js";
+function formatTags(tags) {
+    const shown = tags.slice(0, 8).map(tag => `§${String(tag)}§`);
+    return tags.length > 8 ? `${shown.join(', ')}, …` : shown.join(', ');
+}
+/**
+ * Read-only empty-queue detail. It uses the filtered store query rather than
+ * `Journal.tail`, because `tail` has a fixed row window and is not filtered by
+ * kind: a session with enough `pass`/`tool-call` rows would hide an older
+ * `drop-landed` row. Both the query and date formatting stay inside this
+ * helper's catch; a feedback failure must not turn a successful no-op into an
+ * error.
+ */
+function lastLandingDetail(stores, sessionId) {
+    try {
+        const row = stores.listJournal({
+            sessionId,
+            kinds: ['drop-landed'],
+            limit: 1,
+        })[0];
+        if (row === undefined)
+            return undefined;
+        const at = new Date(row.at).toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, 'Z');
+        const count = row.data?.count;
+        if (typeof count === 'number' && Number.isFinite(count)) {
+            return `last drop landing: ${String(count)} drop(s) at ${at}`;
+        }
+        return `last drop landing at ${at}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function plan(stores, sessionId) {
+    const pending = stores.listPendingDrops(sessionId);
+    const markedBefore = new Set(stores.listFlushRequestedDrops(sessionId));
+    const alreadyRequested = markedBefore.size;
+    if (pending.length === 0) {
+        const lastLanding = lastLandingDetail(stores, sessionId);
+        return {
+            kind: 'success',
+            text: lastLanding === undefined
+                ? 'Magic Context: nothing to flush (no pending drops).'
+                : `Magic Context: nothing to flush now; ${lastLanding}. That landing is already in effect; this call changed nothing.`,
+            requested: 0,
+            alreadyRequested: 0,
+            pendingNext: 0,
+            tags: [],
+        };
+    }
+    const requested = stores.requestFlush(sessionId);
+    if (requested === 0 && alreadyRequested === 0) {
+        // The row was landed (or otherwise changed) between the read and the
+        // UPDATE. That is a successful no-op, not a fabricated failure.
+        return {
+            kind: 'success',
+            text: 'Magic Context: nothing to flush (the pending rows were already landed or changed).',
+            requested: 0,
+            alreadyRequested: 0,
+            pendingNext: pending.length,
+            tags: [],
+        };
+    }
+    let tags;
+    try {
+        tags = stores.listFlushRequestedDrops(sessionId);
+    }
+    catch (error) {
+        return {
+            kind: 'error',
+            text: `Magic Context: flush marker written for ${String(requested)} drop(s), but the queue could not be read: ${errText(error)}.`,
+            requested,
+            alreadyRequested,
+            tags: [],
+        };
+    }
+    const newTags = tags.filter(tag => !markedBefore.has(tag));
+    const oldTags = tags.filter(tag => markedBefore.has(tag));
+    const detail = [
+        newTags.length > 0 ? `new ${formatTags(newTags)}` : '',
+        oldTags.length > 0 ? `already marked ${formatTags(oldTags)}` : '',
+    ].filter(part => part !== '').join('; ');
+    const lead = requested > 0
+        ? `flush queued for ${String(requested)} new drop(s)`
+        : `flush already marked for ${String(alreadyRequested)} drop(s)`;
+    return {
+        kind: 'success',
+        text: `Magic Context: ${lead}${detail === '' ? '' : ` (${detail})`}: requested ${String(requested)}, already marked ${String(alreadyRequested)}, processed 0, pendingNext ${String(pending.length)} (upper bound). Changes take effect on the next message; the current request is unchanged.`,
+        requested,
+        alreadyRequested,
+        pendingNext: pending.length,
+        tags,
+    };
+}
+/**
+ * Result builder for the command and its tests. It never touches the surface;
+ * it reads/writes the queue markers and, only on an empty queue, reads the
+ * newest `drop-landed` journal row for the feedback text.
+ */
+export function planFlushCommand(stores, sessionId) {
+    if (sessionId === undefined || sessionId === '') {
+        return {
+            kind: 'error',
+            text: 'Magic Context: no active session; nothing to flush.',
+            requested: 0,
+            alreadyRequested: 0,
+            tags: [],
+        };
+    }
+    if (stores.closed) {
+        return {
+            kind: 'error',
+            text: 'Magic Context: the store is closed; nothing was changed.',
+            requested: 0,
+            alreadyRequested: 0,
+            tags: [],
+        };
+    }
+    try {
+        return plan(stores, sessionId);
+    }
+    catch (error) {
+        return {
+            kind: 'error',
+            text: `Magic Context: flush failed: ${errText(error)}; nothing was changed.`,
+            requested: 0,
+            alreadyRequested: 0,
+            tags: [],
+        };
+    }
+}
+export function registerCtxFlushCommand(ctx, deps) {
+    const commands = ctx.get('commands');
+    if (commands === undefined) {
+        ctx.logger.warn('magic-context dsh adapter: commands service not mounted; /ctx-flush unavailable');
+        return;
+    }
+    commands.register({
+        name: 'ctx-flush',
+        description: 'Force this session\'s pending ctx_reduce drops to land on the next message (no summary or model call); when the queue is empty, report the last landing for this session.',
+        handler: invocation => {
+            const receipt = planFlushCommand(deps.stores, invocation.agent?.session?.id);
+            return receipt.kind === 'success'
+                ? { kind: 'success', text: receipt.text }
+                : { kind: 'error', text: receipt.text };
+        },
+    });
+}