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

package/lib/dsh/tool-bridge.js

@@ -1,1009 +0,0 @@
-import { estimateTokens } from "../core/compartments.js";
-import { parseTagRanges } from "../core/policy.js";
-import { enumerateSurfaceToolResults, originalContentOfToolCall, toolResultAt, } from "./seams.js";
-/** Probe for the loading-mode diagnostics: resolves the dynamic-import constructor. */
-export function resolveDefineTool() {
-    // The host builder takes its own (wider) option type; the seam names the
-    // subset we author, so the call sites keep their parameter types.
-    return import('@deepseek-ai/dsh-tools').then(module => module.defineTool);
-}
-/**
- * The session id, when the host supplied a run context. A tool must never
- * throw because the context is missing (a host may call it bare): the memory
- * tool then answers without a session and leaves the recall decision to the
- * host's callback.
- */
-function sessionIdOf(exec) {
-    return exec?.agent?.session.id;
-}
-function ackText(lines) {
-    return [{ type: 'text', text: lines.join('\n') }];
-}
-/** Decimal spelling shared by `message` and range bounds; no whitespace or sign. */
-const DECIMAL_SEQ = /^(?:0|[1-9]\d*)$/;
-/** Validate one range bound spelling without ever number-coercing it. */
-function rangeBound(raw, label) {
-    if (typeof raw !== 'string' || !DECIMAL_SEQ.test(raw)) {
-        return { reason: `${label} must be a non-negative decimal integer string` };
-    }
-    const value = Number(raw);
-    if (!Number.isSafeInteger(value)) {
-        return { reason: `${label} must be a non-negative decimal integer string` };
-    }
-    return { value };
-}
-/**
- * Resolve `tag` (canonical, single), `tags` (deprecated multi-tag alias),
- * `message` (DSH log event seq; T3), or an inclusive `start`/`end` range
- * (V1.1). Empty optional strings are absent except for a lone `message`, which
- * is still an invalid value rather than a silent fall-through.
- *
- * Precedence is deliberately range-first: a real range plus another locator is
- * a mixed-locator error even when the other locator pair is itself invalid;
- * host filler `start="0",end="0"` is ignored when a tag/message is present.
- */
-function expandRequest(args) {
-    const tag = typeof args.tag === 'string' ? args.tag.trim() : '';
-    const tags = typeof args.tags === 'string' ? args.tags.trim() : '';
-    const rangeIntent = (args.start !== undefined && args.start !== '')
-        || (args.end !== undefined && args.end !== '');
-    if (args.verbose !== undefined && typeof args.verbose !== 'boolean') {
-        return rangeIntent ? { reason: 'verbose must be a boolean', locator: 'range' } : { reason: 'verbose must be a boolean' };
-    }
-    const verbose = args.verbose === true;
-    const startProvided = args.start !== undefined && args.start !== '';
-    const endProvided = args.end !== undefined && args.end !== '';
-    if (startProvided !== endProvided) {
-        return { reason: 'pass both start and end (DSH log event seq, inclusive)', locator: 'range' };
-    }
-    const hasTagOrMessage = tag !== '' || tags !== '' || (args.message !== undefined && args.message !== '');
-    if (startProvided && endProvided) {
-        // Upstream sends this filler when a range-capable host also fills the
-        // bounds; it means "no range" only when another locator is present.
-        const filler = args.start === '0' && args.end === '0';
-        if (!(filler && hasTagOrMessage)) {
-            if (hasTagOrMessage) {
-                return { reason: 'pass either tag, tags, message, or start/end, not more than one', locator: 'range' };
-            }
-            const start = rangeBound(args.start, 'start');
-            if ('reason' in start)
-                return { ...start, locator: 'range' };
-            const end = rangeBound(args.end, 'end');
-            if ('reason' in end)
-                return { ...end, locator: 'range' };
-            if (start.value > end.value)
-                return { reason: 'start must not be greater than end', locator: 'range' };
-            return { kind: 'range', start: start.value, end: end.value, verbose };
-        }
-    }
-    if (tag !== '' && tags !== '')
-        return { reason: 'pass either tag or tags, not both' };
-    // An empty optional string is how a host often spells "unset" (tag/tags do
-    // the same above). Ignore it only when another locator is present; alone it
-    // is still an invalid `message`, not a silent fall-through to "no tag".
-    if (args.message !== undefined && args.message !== '') {
-        if (tag !== '' || tags !== '') {
-            return { reason: 'pass either tag, tags, or message, not more than one' };
-        }
-        if (typeof args.message !== 'string' || !DECIMAL_SEQ.test(args.message)) {
-            return { reason: 'message must be a non-negative decimal integer string' };
-        }
-        const seq = Number(args.message);
-        if (!Number.isSafeInteger(seq)) {
-            return { reason: `"${args.message}" is outside the safe integer range` };
-        }
-        return { kind: 'message', message: seq };
-    }
-    if (tag === '' && tags === '') {
-        if (args.message !== undefined) {
-            return { reason: 'message must be a non-negative decimal integer string' };
-        }
-        if (args.verbose !== undefined)
-            return { reason: 'verbose requires start and end', locator: 'range' };
-        if (args.start !== undefined || args.end !== undefined) {
-            return { reason: 'start and end must both be provided', locator: 'range' };
-        }
-        return { reason: 'no tag given (pass tag: "N")' };
-    }
-    const source = tag !== '' ? tag : tags;
-    // Request order is the payload order (contract D4/Q3): "9,2" restores 9
-    // first. Only this path keeps it; `ctx_reduce` stays ascending.
-    const parsed = parseTagRanges(source, { preserveOrder: true });
-    if (parsed.length === 0)
-        return { reason: `"${source}" names no tag number` };
-    if (tag !== '' && parsed.length !== 1) {
-        return { reason: `"${source}" is not a single tag number (use tags for several)` };
-    }
-    return { kind: 'tags', tags: parsed };
-}
-/** The post-`getTag` gate shared by the tag and message locators. */
-function restoreResolvedTag(deps, sessionId, tag, original) {
-    const state = deps.stores.dropState(sessionId, tag);
-    if (state === 'pending')
-        return { reason: 'not dropped yet' };
-    if (original.kind === 'missing-event')
-        return { reason: 'tag no longer available' };
-    // A landed drop has a placeholder event in the log; an emergency drop
-    // bypassed the queue but left the same placeholder behind. The guard is
-    // sound because the post-execute hook prefixes EVERY tagged tool result, so
-    // an unprefixed, placeholder-shaped event can only be a drop.
-    if (state !== 'landed' && original.droppedTag === undefined) {
-        return { reason: 'not dropped' };
-    }
-    if (original.kind === 'missing-source')
-        return { reason: 'raw source unavailable' };
-    return { content: original.content };
-}
-/** One payload per restored tag, in request order (contract D4/Q3). */
-function joinExpandPayloads(payloads) {
-    if (payloads.length === 0)
-        return undefined;
-    const blocks = [];
-    for (const [index, content] of payloads.entries()) {
-        // The separator is a block so non-text payloads are carried through
-        // unchanged; a text-only projection reads `p1\n\n---\n\np2`.
-        if (index > 0)
-            blocks.push({ type: 'text', text: '\n\n---\n\n' });
-        blocks.push(...content);
-    }
-    return blocks;
-}
-/** V1.1 range budget: chars/4, same estimate as the rest of the adapter. */
-const CTX_EXPAND_RANGE_TOKEN_BUDGET = 15_000;
-/** Verbose preview length per part (upstream-compatible). */
-const CTX_EXPAND_PREVIEW_CHARS = 200;
-/** Reserve for the header, continuation, and token-estimate rounding. */
-const CTX_EXPAND_HEADER_RESERVE = 400;
-const COMPACTED_RANGE_TEXT = /^\[compacted §C\d+§\]$/;
-const EXCLUDED_RANGE_SOURCE_KINDS = new Set(['magic-context', 'compact-checkpoint']);
-function isRangeReadableEvent(event) {
-    return event.type === 'user/message' || event.type === 'assistant/message' || event.type === 'tool/result';
-}
-function rangeContent(event) {
-    return event.type === 'user/message' ? event.data.content : event.data.message.content;
-}
-function rangeSourceKind(event) {
-    const source = event.type === 'user/message' ? event.data.source : event.data.message.source;
-    return source?.kind;
-}
-/** Exclude adapter/host bookkeeping and compacted markers from transcript output. */
-function isExcludedRangeEvent(event) {
-    const kind = rangeSourceKind(event);
-    // A user message belongs in the transcript only when it came from the user.
-    // Adapter notices, compaction checkpoints and other plugin-injected user
-    // messages are context, not conversation; unknown future kinds stay out.
-    if (event.type === 'user/message' && kind !== undefined && kind !== 'user')
-        return true;
-    if (kind !== undefined && EXCLUDED_RANGE_SOURCE_KINDS.has(kind))
-        return true;
-    return rangeContent(event).some(block => block.type === 'text' && COMPACTED_RANGE_TEXT.test(block.text.trim()));
-}
-function compactArguments(raw) {
-    if (typeof raw !== 'string') {
-        try {
-            return JSON.stringify(raw) ?? '';
-        }
-        catch {
-            return '';
-        }
-    }
-    try {
-        return JSON.stringify(JSON.parse(raw)) ?? raw;
-    }
-    catch {
-        return raw;
-    }
-}
-function previewPart(text) {
-    // Code-point slice so a preview never ends on a lone surrogate.
-    return Array.from(text.replace(/\s+/gu, ' ').trim()).slice(0, CTX_EXPAND_PREVIEW_CHARS).join('');
-}
-function blockName(block) {
-    if (block.type !== 'image')
-        return block.type;
-    const image = block;
-    const detail = typeof image.attachment?.name === 'string'
-        ? image.attachment.name
-        : typeof image.attachment?.mediaType === 'string'
-            ? image.attachment.mediaType
-            : '';
-    return detail === '' ? 'image' : `image ${detail}`;
-}
-function rangeLabel(event, toolNames) {
-    if (event.type === 'user/message')
-        return 'user/message';
-    if (event.type === 'assistant/message')
-        return 'assistant/message';
-    const callId = String(event.data.message.toolCallId);
-    const name = toolNames.get(callId);
-    return name === undefined ? `tool/result (${callId})` : `tool/result ${name} (${callId})`;
-}
-/** Render one readable event as text; tool calls are text, never executable blocks. */
-function renderRangeEvent(event, toolNames, verbose) {
-    const lines = [`[${String(event.seq)}] ${rangeLabel(event, toolNames)}`];
-    for (const block of rangeContent(event)) {
-        if (block.type === 'text') {
-            if (verbose) {
-                if (block.text !== '')
-                    lines.push(`  • [text] ${previewPart(block.text)}`);
-            }
-            else if (block.text !== '') {
-                lines.push(block.text);
-            }
-            continue;
-        }
-        if (block.type === 'tool-call') {
-            const call = String(block.id);
-            const identity = `${block.name} (${call})`;
-            const args = compactArguments(block.arguments);
-            if (verbose) {
-                lines.push(`  • [tool-call] ${identity} ${previewPart(args)}`);
-            }
-            else {
-                lines.push(`[${String(event.seq)}] tool call ${identity}`);
-                lines.push(args);
-            }
-            continue;
-        }
-        // Reasoning is not transcript content; other non-text parts are named.
-        if (block.type === 'reasoning')
-            continue;
-        lines.push(verbose ? `  • [${blockName(block)}]` : `[${blockName(block)}]`);
-    }
-    return lines.join('\n');
-}
-function truncateToTokenBudget(text, maxTokens) {
-    if (maxTokens <= 0)
-        return '';
-    if (estimateTokens(text) <= maxTokens)
-        return text;
-    let low = 0;
-    let high = text.length;
-    while (low < high) {
-        const mid = Math.ceil((low + high) / 2);
-        if (estimateTokens(text.slice(0, mid)) <= maxTokens)
-            low = mid;
-        else
-            high = mid - 1;
-    }
-    let end = low;
-    // Do not split a UTF-16 surrogate pair at the budget boundary.
-    if (end > 0 && /[\uD800-\uDBFF]/.test(text[end - 1] ?? ''))
-        end -= 1;
-    return text.slice(0, end);
-}
-/**
- * Render selected readable events with the shared budget. `skipped` counts
- * every in-bounds event that did not become a rendered section, including
- * excluded types/source kinds and anything after an ordinary budget cut; seq
- * gaps are not events and never count.
- */
-function renderRangeTranscript(events, inBoundsCount, start, end, verbose, toolNames) {
-    const bodyBudget = CTX_EXPAND_RANGE_TOKEN_BUDGET - CTX_EXPAND_HEADER_RESERVE;
-    const sections = [];
-    const included = [];
-    let trailer = '';
-    for (const event of events) {
-        const section = renderRangeEvent(event, toolNames, verbose);
-        const candidate = [...sections, section].join('\n\n');
-        if (estimateTokens(candidate) <= bodyBudget) {
-            sections.push(section);
-            included.push(event.seq);
-            continue;
-        }
-        if (sections.length === 0) {
-            // One oversized event: keep a bounded head instead of returning an
-            // unbounded result. The continuation must not suggest start=<seq+1>,
-            // which would skip the unread remainder.
-            const marker = '[event truncated]';
-            const continuation = `Event ${String(event.seq)} truncated at the budget; narrow start/end to read the remainder (tag/message only restore dropped tool results).`;
-            const available = Math.max(1, bodyBudget - estimateTokens(marker) - estimateTokens(continuation) - 2);
-            sections.push(`${truncateToTokenBudget(section, available)}\n${marker}`);
-            included.push(event.seq);
-            trailer = continuation;
-        }
-        else {
-            const last = included[included.length - 1] ?? start;
-            const verbosity = verbose ? ' verbose=true' : '';
-            trailer = `Truncated at event ${String(last)} (budget: ~15000 estimated tokens). Call again with start=${String(last + 1)} end=${String(end)}${verbosity}.`;
-        }
-        break;
-    }
-    const skipped = Math.max(0, inBoundsCount - included.length);
-    const header = verbose
-        ? `Events ${String(start)}-${String(end)} (verbose; ${String(included.length)} events, ${String(skipped)} skipped). Recover a full dropped tool result with tag or message.`
-        : `Events ${String(start)}-${String(end)} (${String(included.length)} events, ${String(skipped)} skipped):`;
-    return {
-        text: [header, ...sections, ...trailer === '' ? [] : [trailer]].join('\n\n'),
-        events: included,
-        skipped,
-    };
-}
-export function defineCtxReduceTool(deps) {
-    const defineTool = deps.defineTool;
-    return defineTool({
-        name: 'ctx_reduce',
-        description: 'Mark conversation items you no longer need so their tokens are reclaimed. '
-            + 'Pass tag IDs you saw on tool outputs: drop: "3-5, 1, 9". '
-            + 'Marks are queued and land when the context manager opens its reclaim band; '
-            + 'dropped tool outputs become `[dropped §N§]` placeholders. Nothing is lost: '
-            + 'ctx_expand returns any original as a new result (the placeholder stays dropped).',
-        parameters: { drop: { type: 'string', required: true } },
-        output: {
-            schema: { type: 'json' },
-            render: (_args, value) => {
-                const payload = value;
-                const lines = [];
-                const queued = payload.queued ?? [];
-                // A count, not a list (MC 0.49.1 parity): the tags came from the agent's
-                // own surface, so echoing them back is pure noise, and the noise grows
-                // linearly with the batch. Refusals stay per-tag: each one is an
-                // actionable failure the agent must not retry blindly.
-                if (queued.length > 0) {
-                    lines.push(`Queued ${String(queued.length)} ${queued.length === 1 ? 'tag' : 'tags'} for reclaim.`);
-                }
-                for (const refused of payload.refused ?? []) {
-                    lines.push(`§${refused.tag}§ not queued: ${refused.reason ?? 'unavailable'}.`);
-                }
-                if (lines.length === 0)
-                    lines.push('Nothing queued.');
-                return ackText(lines);
-            },
-        },
-        async execute(args, exec) {
-            const startedAt = Date.now();
-            const sessionId = sessionIdOf(exec);
-            if (sessionId === undefined)
-                return { ok: false, queued: [], refused: [], reason: 'no-session' };
-            const requested = parseTagRanges(args.drop);
-            const nodes = enumerateSurfaceToolResults(exec.agent.session, callId => deps.stores.getTag(sessionId, { kind: 'tool-result', callId }));
-            const queued = [];
-            const refused = [];
-            const now = Date.now();
-            for (const tag of requested) {
-                // Durable lifecycle first (#13 A): a spent tag stays refused even when
-                // its placeholder has left the live surface (historian publication), and
-                // a queued tag is refused explicitly as `already queued` rather than
-                // being written again.
-                const state = deps.stores.dropState(sessionId, tag);
-                if (state === 'landed') {
-                    refused.push({ tag, ok: false, reason: 'already dropped' });
-                    continue;
-                }
-                if (state === 'pending') {
-                    refused.push({ tag, ok: false, reason: 'already queued' });
-                    continue;
-                }
-                const node = nodes.find(candidate => candidate.tagNumber === tag);
-                if (node === undefined) {
-                    refused.push({ tag, ok: false, reason: 'no such tool-output tag on the current surface' });
-                    continue;
-                }
-                if (node.isPlaceholder) {
-                    // A drop the emergency band performed never entered the queue, so its
-                    // durable state is still `none`; the live placeholder is the record.
-                    refused.push({ tag, ok: false, reason: 'already dropped' });
-                    continue;
-                }
-                deps.stores.queueDrop(sessionId, tag, now);
-                queued.push(tag);
-            }
-            deps.journal?.info('tool-call', `ctx_reduce: queued ${String(queued.length)}, refused ${String(refused.length)}`, {
-                tool: 'ctx_reduce',
-                requested,
-                queued,
-                refused: refused.map(entry => ({ tag: entry.tag, reason: entry.reason })),
-                ms: Date.now() - startedAt,
-            }, sessionId);
-            return { ok: true, queued, refused };
-        },
-    });
-}
-export function defineCtxExpandTool(deps) {
-    const defineTool = deps.defineTool;
-    return defineTool({
-        name: 'ctx_expand',
-        description: 'Read or restore context. Locators (mutually exclusive): tag — or the deprecated tags alias — restores '
-            + 'a dropped tool result as a new result; message restores one dropped tool result by DSH log event seq; '
-            + 'start/end reads an inclusive range of DSH log events as a read-only transcript. '
-            + 'Ranges use DSH log event seq, not upstream Magic Context message ordinals. '
-            + 'A range does not require a prior drop and never changes drop state; verbose previews each event '
-            + '(200 characters per part) instead of returning full bodies. '
-            + 'For tag/message, the original content returns as this tool result; the old `[dropped §N§]` placeholder '
-            + 'stays in place and its tag stays spent (drop the new result if you no longer need it).',
-        parameters: {
-            tag: { type: 'string', description: 'Canonical single tag, e.g. "3".' },
-            tags: { type: 'string', description: 'Deprecated multi-tag alias, e.g. "3, 7".' },
-            message: {
-                type: 'string',
-                description: 'DSH log event seq of a dropped tool/result or its `[dropped §N§]` placeholder; '
-                    + 'not the original Magic Context message number; `[compacted §C…§]` is not accepted.',
-            },
-            start: {
-                type: 'string',
-                description: 'Inclusive DSH log event seq range start (decimal string). Not an upstream message ordinal. '
-                    + 'Requires end; mutually exclusive with tag/tags/message.',
-            },
-            end: {
-                type: 'string',
-                description: 'Inclusive DSH log event seq range end (decimal string). Requires start.',
-            },
-            verbose: {
-                type: 'boolean',
-                description: 'Preview each range event (200 characters per part) instead of full bodies.',
-            },
-        },
-        output: {
-            schema: { type: 'json' },
-            render: (_args, value) => {
-                const payload = value;
-                const lines = [];
-                if (payload.reason !== undefined)
-                    lines.push(`ctx_expand refused: ${payload.reason}.`);
-                for (const refused of payload.refused ?? []) {
-                    lines.push(`§${refused.tag}§ not restored: ${refused.reason ?? 'unavailable'}.`);
-                }
-                const content = payload.content ?? [];
-                if (content.length > 0) {
-                    // The payload IS the restored original. A partial multi-tag request
-                    // (deprecated `tags`) appends its refusals after the payload so a
-                    // successful single-tag result stays byte-identical to the original.
-                    return lines.length === 0
-                        ? [...content]
-                        : [...content, { type: 'text', text: `\n\n${lines.join('\n')}` }];
-                }
-                if (lines.length === 0)
-                    lines.push('Nothing restored.');
-                return ackText(lines);
-            },
-        },
-        async execute(args, exec) {
-            const startedAt = Date.now();
-            const sessionId = sessionIdOf(exec);
-            if (sessionId === undefined)
-                return { ok: false, restored: [], refused: [], reason: 'no-session' };
-            const request = expandRequest(args);
-            if ('reason' in request) {
-                if (request.locator === 'range') {
-                    deps.journal?.info('tool-call', 'ctx_expand: read 0 events (refused)', {
-                        tool: 'ctx_expand',
-                        locator: 'range',
-                        start: args.start,
-                        end: args.end,
-                        verbose: args.verbose,
-                        events: [],
-                        skipped: 0,
-                        reason: request.reason,
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, locator: 'range', reason: request.reason };
-                }
-                deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                    tool: 'ctx_expand',
-                    requested: [],
-                    restored: [],
-                    refused: [],
-                    reason: request.reason,
-                    ms: Date.now() - startedAt,
-                }, sessionId);
-                return { ok: false, restored: [], refused: [], reason: request.reason };
-            }
-            const session = exec.agent.session;
-            if (request.kind === 'range') {
-                const events = session.snapshotEvents();
-                const inBounds = events.filter(event => event.seq >= request.start && event.seq <= request.end);
-                const readable = inBounds
-                    .filter(isRangeReadableEvent)
-                    .filter(event => !isExcludedRangeEvent(event));
-                if (readable.length === 0) {
-                    const reason = `no readable events in range ${String(request.start)}-${String(request.end)}`;
-                    deps.journal?.info('tool-call', 'ctx_expand: read 0 events (no readable)', {
-                        tool: 'ctx_expand',
-                        locator: 'range',
-                        start: request.start,
-                        end: request.end,
-                        verbose: request.verbose,
-                        events: [],
-                        skipped: inBounds.length,
-                        reason,
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, locator: 'range', reason };
-                }
-                const live = new Set(session.surface.nodes);
-                if (readable.every(event => live.has(event.seq))) {
-                    const text = `Events ${String(request.start)}-${String(request.end)} are already on the live surface; no raw history was read.`;
-                    deps.journal?.info('tool-call', 'ctx_expand: read 0 events (live surface)', {
-                        tool: 'ctx_expand',
-                        locator: 'range',
-                        start: request.start,
-                        end: request.end,
-                        verbose: request.verbose,
-                        events: [],
-                        skipped: inBounds.length - readable.length,
-                        liveSurface: true,
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: true, locator: 'range', events: [], content: [{ type: 'text', text }] };
-                }
-                const toolNames = new Map();
-                for (const event of events) {
-                    if (event.type === 'tool/call')
-                        toolNames.set(event.data.callId, event.data.name);
-                }
-                const rendered = renderRangeTranscript(readable, inBounds.length, request.start, request.end, request.verbose, toolNames);
-                deps.journal?.info('tool-call', `ctx_expand: read ${String(rendered.events.length)} event(s)`, {
-                    tool: 'ctx_expand',
-                    locator: 'range',
-                    start: request.start,
-                    end: request.end,
-                    verbose: request.verbose,
-                    events: rendered.events,
-                    skipped: rendered.skipped,
-                    ms: Date.now() - startedAt,
-                }, sessionId);
-                return {
-                    ok: true,
-                    locator: 'range',
-                    events: rendered.events,
-                    content: [{ type: 'text', text: rendered.text }],
-                };
-            }
-            if (request.kind === 'message') {
-                const lookup = toolResultAt(session, request.message);
-                if (lookup.kind === 'unknown') {
-                    deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                        tool: 'ctx_expand',
-                        requested: [],
-                        message: request.message,
-                        restored: [],
-                        refused: [],
-                        reason: 'no such message',
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, restored: [], refused: [], reason: 'no such message' };
-                }
-                if (lookup.kind === 'not-tool-result') {
-                    deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                        tool: 'ctx_expand',
-                        requested: [],
-                        message: request.message,
-                        restored: [],
-                        refused: [],
-                        reason: 'not a tool-result message',
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, restored: [], refused: [], reason: 'not a tool-result message' };
-                }
-                const original = originalContentOfToolCall(session, lookup.callId);
-                const registeredTag = deps.stores.getTag(sessionId, { kind: 'tool-result', callId: lookup.callId });
-                // A message may point at the original event while the same call also
-                // has a placeholder; the call-level droppedTag is the evidence, not the
-                // shape of the event the caller named.
-                const callDroppedTag = original.kind === 'missing-event' ? undefined : original.droppedTag;
-                const tag = registeredTag ?? callDroppedTag;
-                if (tag === undefined) {
-                    deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                        tool: 'ctx_expand',
-                        requested: [],
-                        message: request.message,
-                        restored: [],
-                        refused: [],
-                        reason: 'not a tool-result tag',
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, restored: [], refused: [], reason: 'not a tool-result tag' };
-                }
-                if (registeredTag === undefined) {
-                    deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                        tool: 'ctx_expand',
-                        requested: [],
-                        message: request.message,
-                        restored: [],
-                        refused: [],
-                        reason: 'tag no longer available',
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, restored: [], refused: [], reason: 'tag no longer available' };
-                }
-                const outcome = restoreResolvedTag(deps, sessionId, tag, original);
-                if ('reason' in outcome) {
-                    deps.journal?.info('tool-call', 'ctx_expand: restored 0, refused 0', {
-                        tool: 'ctx_expand',
-                        requested: [],
-                        message: request.message,
-                        restored: [],
-                        refused: [],
-                        reason: outcome.reason,
-                        ms: Date.now() - startedAt,
-                    }, sessionId);
-                    return { ok: false, restored: [], refused: [], reason: outcome.reason };
-                }
-                deps.journal?.info('tool-call', 'ctx_expand: restored 1, refused 0', {
-                    tool: 'ctx_expand',
-                    requested: [],
-                    message: request.message,
-                    restored: [tag],
-                    refused: [],
-                    ms: Date.now() - startedAt,
-                }, sessionId);
-                return { ok: true, restored: [tag], refused: [], content: outcome.content };
-            }
-            // Resolve the tag's persisted call identity — no live placeholder is
-            // required, so a historian-published or restarted session reads the same
-            // original from the log (contract D1.4, E4).
-            const records = new Map(deps.stores.listTags(sessionId).map(record => [record.tagNumber, record]));
-            const restored = [];
-            const refused = [];
-            const payloads = [];
-            for (const tag of request.tags) {
-                const record = records.get(tag);
-                if (record === undefined) {
-                    // Tag numbers are per-session (contract D5). The global index names a
-                    // foreign owner only when this session has no tag records at all: once
-                    // it holds any tag of its own, its numbering is live, so a number it
-                    // never used is a typo, not a handle from another session.
-                    const crossSession = records.size === 0
-                        && deps.stores.tagSessions(tag).some(other => other !== sessionId);
-                    refused.push({ tag, ok: false, reason: crossSession ? 'cross-session tag' : 'no such tag' });
-                    continue;
-                }
-                if (record.target.kind !== 'tool-result') {
-                    refused.push({ tag, ok: false, reason: 'not a tool-result tag' });
-                    continue;
-                }
-                const original = originalContentOfToolCall(session, record.target.callId);
-                const outcome = restoreResolvedTag(deps, sessionId, tag, original);
-                if ('reason' in outcome) {
-                    refused.push({ tag, ok: false, reason: outcome.reason });
-                    continue;
-                }
-                payloads.push(outcome.content);
-                restored.push(tag);
-            }
-            const content = joinExpandPayloads(payloads);
-            deps.journal?.info('tool-call', `ctx_expand: restored ${String(restored.length)}, refused ${String(refused.length)}`, {
-                tool: 'ctx_expand',
-                requested: request.tags,
-                restored,
-                refused: refused.map(entry => ({ tag: entry.tag, reason: entry.reason })),
-                ms: Date.now() - startedAt,
-            }, sessionId);
-            return { ok: true, restored, refused, ...content === undefined ? {} : { content } };
-        },
-    });
-}
-export function defineCtxMemoryTool(deps) {
-    const defineTool = deps.defineTool;
-    /**
-     * The session's project identity, which every write must carry: Magic Context
-     * only lets an agent mutate its own project's memories.
-     */
-    const identityFor = (exec) => {
-        try {
-            return deps.resolveIdentity?.(exec);
-        }
-        catch {
-            return undefined;
-        }
-    };
-    return defineTool({
-        name: 'ctx_memory',
-        description: 'Read and maintain the project memory store (shared with the other coding agents on this machine): '
-            + 'durable facts, constraints, configuration values and naming rules. '
-            + 'Actions: list (optionally with query), search (hybrid keyword+semantic retrieval over the pool, '
-            + 'optionally bounded by from/to dates), '
-            + 'get (by id), write (new memory), update (rewrite one), '
-            + 'archive (retire one, optionally superseded by another), merge (fold duplicates into one), '
-            + 'review_global (present pending global-domain candidates — the work and global audiences — to the user as '
-            + 'approval cards, one at a time; an approved candidate is published into the shared domain), '
-            + 'promote (memory_id + optional domain machine|org — machine is the GLOBAL domain every project on '
-            + 'this machine sees, org is the WORK domain limited to its member projects: enqueue one project memory '
-            + 'into that domain and IMMEDIATELY raise its approval card — approved publishes, rejected retires it for '
-            + 'good; the human-judged lane with no recurrence gate, so a single fresh write can be shared '
-            + 'right away). '
-            + 'Writes are scoped to this project and deduplicated by normalized content. '
-            + 'Every action accepts an optional project (an absolute path or git root): use it when the '
-            + 'memory belongs to ANOTHER project than the one this session was opened in — reading a '
-            + "project's memories or writing facts about it while you work on it from a different session.",
-        parameters: {
-            action: { type: 'string', enum: ['list', 'search', 'get', 'write', 'update', 'archive', 'merge', 'review_global', 'promote'] },
-            query: { type: 'string' },
-            limit: { type: 'integer' },
-            from: { type: 'string' },
-            to: { type: 'string' },
-            id: { type: 'integer' },
-            ids: { type: 'array', items: { type: 'integer' } },
-            category: { type: 'string' },
-            content: { type: 'string' },
-            importance: { type: 'integer' },
-            reason: { type: 'string' },
-            superseded_by: { type: 'integer' },
-            target_id: { type: 'integer' },
-            project: { type: 'string' },
-            memory_id: { type: 'integer' },
-            domain: { type: 'string' },
-        },
-        output: {
-            schema: { type: 'json' },
-            render: (_args, value) => {
-                const payload = value;
-                if (payload.reason !== undefined)
-                    return ackText([`Memory store unavailable: ${payload.reason}`]);
-                if (payload.search !== undefined)
-                    return ackText([String(payload.search)]);
-                if (payload.outcome !== undefined) {
-                    return ackText([payload.outcome, ...payload.detail === undefined ? [] : [payload.detail]]);
-                }
-                if (payload.memory !== undefined) {
-                    return ackText([
-                        `Memory ${String(payload.memory.id)} [${payload.memory.category}] (importance ${String(payload.memory.importance)}):`,
-                        payload.memory.content,
-                    ]);
-                }
-                if (payload.empty === true || payload.lines === undefined || payload.lines.length === 0) {
-                    return ackText(['No matching project memories.']);
-                }
-                return ackText([
-                    `Project memories (${String(payload.lines.length)} shown):`,
-                    ...payload.lines,
-                ]);
-            },
-        },
-        async execute(args, exec) {
-            const startedAt = Date.now();
-            const sessionId = sessionIdOf(exec);
-            const action = typeof args.action === 'string' ? args.action : 'list';
-            // Effective scope: the session's project unless the model names another
-            // one via `project`. An unresolvable spec is a structured refusal — the
-            // model then knows the write/read did NOT happen under some guessed scope.
-            const explicitProject = typeof args.project === 'string' && args.project.trim() !== ''
-                ? args.project.trim()
-                : undefined;
-            let identity = identityFor(exec);
-            const finish = (payload) => {
-                const summary = payload.outcome
-                    ?? (payload.memory !== undefined
-                        ? `memory ${payload.memory.id}`
-                        : payload.search !== undefined
-                            ? `search: ${String(payload.hits ?? 0)} result(s)`
-                            : `${String(payload.lines?.length ?? 0)} line(s)`);
-                deps.journal?.info('tool-call', `ctx_memory ${action}: ${String(summary)}`, {
-                    tool: 'ctx_memory',
-                    action,
-                    identity,
-                    ...explicitProject === undefined ? {} : { explicitProject },
-                    query: args.query,
-                    id: args.id,
-                    // The panel's read row shows the hit count (`detail.hits`); without it
-                    // a search record could only say "search".
-                    ...typeof payload.hits === 'number' ? { hits: payload.hits } : {},
-                    ms: Date.now() - startedAt,
-                    ok: typeof payload.ok === 'boolean' ? payload.ok : payload.reason === undefined,
-                }, sessionId);
-                return payload;
-            };
-            if (explicitProject !== undefined) {
-                let resolved;
-                if (explicitProject.startsWith('git:') || explicitProject.startsWith('dir:')) {
-                    resolved = explicitProject;
-                }
-                else {
-                    try {
-                        resolved = deps.resolveIdentityOf?.(explicitProject);
-                    }
-                    catch {
-                        resolved = undefined;
-                    }
-                }
-                if (resolved === undefined || resolved === '') {
-                    return finish({
-                        outcome: `project "${explicitProject}" could not be resolved to a project identity `
-                            + '(directory missing, or not inside a git repository and not an identity string). '
-                            + 'Nothing was read or written.',
-                        ok: false,
-                    });
-                }
-                identity = resolved;
-            }
-            if (action === 'review_global') {
-                if (deps.reviewGlobal === undefined) {
-                    return finish({ reason: 'global review is not wired in this host' });
-                }
-                const result = await deps.reviewGlobal(exec);
-                return finish(result);
-            }
-            if (action === 'promote') {
-                if (deps.promoteGlobal === undefined) {
-                    return finish({ reason: 'global promotion is not wired in this host' });
-                }
-                if (typeof args.memory_id !== 'number' || !Number.isInteger(args.memory_id)) {
-                    return finish({
-                        outcome: 'promote needs an integer memory_id (the project memory to enqueue for approval). '
-                            + 'Nothing was promoted.',
-                        ok: false,
-                    });
-                }
-                const domain = typeof args.domain === 'string' && args.domain.trim() !== '' ? args.domain.trim() : undefined;
-                const result = await deps.promoteGlobal({ memoryId: args.memory_id, ...(domain === undefined ? {} : { domain }) }, exec);
-                return finish(result);
-            }
-            if (action === 'list' || (action === 'get' && args.id === undefined)) {
-                const recall = deps.recall;
-                if (recall === undefined) {
-                    return finish({ reason: 'memory recall is not wired in this host' });
-                }
-                // The run context goes to the host alongside the request: a host whose
-                // recall callback scopes by `config.memory.project ?? session cwd` has
-                // no other way to see the session (index.ts), and `identity` is the
-                // identity this tool already resolved for the same purpose. The two
-                // model-supplied fields are narrowed here: `args` is the validated
-                // argument record, and a `query`/`limit` of the wrong type must not
-                // reach the host's recall as a non-string / non-number.
-                const query = typeof args.query === 'string' ? args.query : undefined;
-                const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = recall({
-                    ...query === undefined ? {} : { query },
-                    ...limit === undefined ? {} : { limit },
-                    ...identity === undefined ? {} : { identity },
-                }, exec);
-                if (result === undefined)
-                    return finish({ empty: true });
-                // A store the host could not read at all (fenced schema, unreadable file)
-                // must say so: `{ empty: true }` would read as "your project has no
-                // memories", which is a different fact.
-                if (result.lines.length === 0 && result.reason !== undefined) {
-                    return finish({ reason: result.reason });
-                }
-                // Retrieval telemetry (contract §9.1): the agent explicitly searched here,
-                // so the rows it received are counted. Telemetry is never correctness, so
-                // a fenced / authority-blocked / failing store is swallowed and the agent
-                // still gets its lines. An automatic injection path must NOT reach here.
-                const recalledIds = result.ids;
-                if (recalledIds !== undefined && recalledIds.length > 0 && identity !== undefined) {
-                    try {
-                        deps.writer?.recordRetrieval({ identity, ids: [...recalledIds] });
-                    }
-                    catch {
-                        // never fail a read because a counter could not be bumped
-                    }
-                }
-                return finish({ lines: [...result.lines], digest: result.digest });
-            }
-            if (action === 'search') {
-                const query = typeof args.query === 'string' ? args.query.trim() : '';
-                if (query.length === 0)
-                    return finish({ outcome: 'search needs a query.' });
-                if (deps.search === undefined) {
-                    return finish({ reason: 'memory search is not wired in this host' });
-                }
-                if (identity === undefined) {
-                    return finish({ reason: 'no project identity could be resolved for this session' });
-                }
-                // A3: `from`/`to` accept an ISO date (YYYY-MM-DD, local midnight /
-                // end-of-day) or epoch milliseconds; invalid values are ignored.
-                const parseBound = (raw, endOfDay) => {
-                    if (typeof raw === 'number' && Number.isFinite(raw))
-                        return raw;
-                    if (typeof raw !== 'string')
-                        return undefined;
-                    const ms = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(raw) ? raw : raw);
-                    if (Number.isNaN(ms))
-                        return undefined;
-                    return endOfDay ? ms + 24 * 3600 * 1000 - 1 : ms;
-                };
-                const from = parseBound(args.from, false);
-                const to = parseBound(args.to, true);
-                const visibleMemoryIds = deps.visibleMemoryIdsOf?.(exec);
-                const outcome = await deps.search({
-                    query,
-                    ...args.limit === undefined ? {} : { limit: args.limit },
-                    identity,
-                    ...visibleMemoryIds === undefined ? {} : { visibleMemoryIds },
-                    ...from === undefined ? {} : { from },
-                    ...to === undefined ? {} : { to },
-                });
-                if (!outcome.ok)
-                    return finish({ reason: outcome.reason });
-                // Retrieval telemetry (contract §9.1): an explicit search counts, in
-                // MC only through ctx_search — the same rule, same call shape.
-                if (outcome.hits.length > 0) {
-                    try {
-                        deps.writer?.recordRetrieval({ identity, ids: outcome.hits.map(hit => hit.id) });
-                    }
-                    catch {
-                        // never fail a read because a counter could not be bumped
-                    }
-                }
-                return finish({ search: outcome.text, hits: outcome.hits.length });
-            }
-            // Every remaining action writes (or reads one row by id) and needs the
-            // writer plus a resolved identity.
-            const writer = deps.writer;
-            if (writer === undefined) {
-                return finish({ reason: 'memory writes are disabled (memory.enabled / memory.write)' });
-            }
-            if (identity === undefined) {
-                return finish({ reason: 'no project identity could be resolved for this session' });
-            }
-            if (action === 'get') {
-                const row = writer.getMemory(identity, args.id);
-                if (row === undefined)
-                    return finish({ outcome: `No memory ${String(args.id)} in this project.` });
-                // Contract §9.1: a single-row get does NOT count as a retrieval — only
-                // explicit list/query searches do (MC search.ts:2258-2281: "a row read
-                // is not a search"). Pinned by memory-retrieval-wiring.spec.ts.
-                return finish({
-                    memory: { id: row.id, category: row.category, content: row.content, importance: row.importance ?? 50 },
-                });
-            }
-            if (action === 'write') {
-                if (typeof args.content !== 'string' || typeof args.category !== 'string') {
-                    return finish({ outcome: 'write needs both category and content.' });
-                }
-                const result = writer.writeMemory({
-                    identity,
-                    category: args.category,
-                    content: args.content,
-                    ...args.importance === undefined ? {} : { importance: args.importance },
-                    ...sessionId === undefined ? {} : { sessionId },
-                });
-                if (!result.ok)
-                    return finish({ outcome: `write refused (${result.reason}).`, detail: result.detail });
-                return finish({
-                    outcome: result.created === false
-                        ? `Already known (memory ${String(result.id)}, seen ${String(result.seenCount ?? 0)} times).`
-                        : `Saved as memory ${String(result.id)} [${args.category}].`,
-                });
-            }
-            if (action === 'update') {
-                if (args.id === undefined || typeof args.content !== 'string') {
-                    return finish({ outcome: 'update needs id and content.' });
-                }
-                const result = writer.updateMemory({
-                    identity,
-                    id: args.id,
-                    content: args.content,
-                    ...args.category === undefined ? {} : { category: args.category },
-                    ...args.importance === undefined ? {} : { importance: args.importance },
-                });
-                if (!result.ok)
-                    return finish({ outcome: `update refused (${result.reason}).`, detail: result.detail });
-                return finish({ outcome: `Updated memory ${String(result.id)}.` });
-            }
-            if (action === 'archive') {
-                if (args.id === undefined)
-                    return finish({ outcome: 'archive needs id.' });
-                const result = writer.archiveMemory({
-                    identity,
-                    id: args.id,
-                    ...args.reason === undefined ? {} : { reason: args.reason },
-                    ...args.superseded_by === undefined ? {} : { supersededBy: args.superseded_by },
-                });
-                if (!result.ok)
-                    return finish({ outcome: `archive refused (${result.reason}).`, detail: result.detail });
-                return finish({ outcome: `Archived memory ${String(result.id)}.` });
-            }
-            if (action === 'merge') {
-                const target = (args.target_id ?? args.id);
-                const sources = (args.ids ?? []);
-                if (target === undefined || sources.length === 0 || typeof args.content !== 'string') {
-                    return finish({ outcome: 'merge needs target_id, ids and the merged content.' });
-                }
-                const result = writer.mergeMemory({
-                    identity,
-                    targetId: target,
-                    sourceIds: sources,
-                    content: args.content,
-                    ...args.category === undefined ? {} : { category: args.category },
-                });
-                if (!result.ok)
-                    return finish({ outcome: `merge refused (${result.reason}).`, detail: result.detail });
-                return finish({
-                    outcome: `Merged ${String(result.superseded.length)} row(s) into memory ${String(result.id)}.`,
-                });
-            }
-            return finish({ outcome: `Unknown action "${action}".` });
-        },
-    });
-}