dsh-reference-anything 0.2.0

package/lib/opencli.js

@@ -0,0 +1,356 @@
+import { execFile as nodeExecFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+const execFile = promisify(nodeExecFile);
+export const MIN_OPENCLI_VERSION = '1.8.6';
+export const MIN_ADAPTER_VERSION = '0.2.0';
+export const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
+const SITE = {
+    chatgpt: 'dsh-chatgpt', claude: 'dsh-claude', gemini: 'dsh-gemini',
+    deepseek: 'dsh-deepseek', grok: 'dsh-grok', kimi: 'dsh-kimi',
+};
+const REQUIRED_ADAPTER_COMMANDS = ['chatgpt', 'claude', 'gemini', 'deepseek', 'grok', 'kimi'];
+export class OpenCliError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Parse the human-readable `opencli daemon status` output into structured
+ * bridge state. Empty output — including a probe failure — degrades to
+ * `daemon-offline` rather than throwing, so one broken probe never hides the
+ * rest of the viability panel.
+ */
+export function parseDaemonStatus(output) {
+    const daemonRunning = /^Daemon:\s+(?:running|stale)\b/m.test(output);
+    const connected = /^Extension:\s+connected\b/m.test(output);
+    const version = connected ? output.match(/^Extension:\s+connected \((v)?([^)\s]+)\)/m)?.[2] : undefined;
+    const profileRequired = output.match(/^Extension:\s+(\d+) profiles? connected, none selected/m);
+    const profileDisconnected = /^Extension:\s+requested profile not connected/m.test(output);
+    const extensionState = !daemonRunning ? 'daemon-offline'
+        : connected ? 'connected'
+            : profileRequired ? 'profile-required'
+                : profileDisconnected ? 'profile-disconnected'
+                    : 'disconnected';
+    const profileCount = profileRequired ? Number(profileRequired[1]) : undefined;
+    return {
+        daemonRunning, extensionState, extensionConnected: extensionState === 'connected',
+        ...(version ? { extensionVersion: version } : {}),
+        ...(profileCount !== undefined ? { profileCount } : {}),
+    };
+}
+export class OpenCliRunner {
+    executable;
+    profile;
+    prefixArgs;
+    timeoutMs;
+    maxStdoutBytes;
+    constructor(options = {}) {
+        this.executable = options.executable || 'opencli';
+        this.profile = options.profile || '';
+        this.prefixArgs = options.prefixArgs ?? [];
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxStdoutBytes = options.maxStdoutBytes ?? 32 * 1024 * 1024;
+    }
+    async whoami(provider, signal) {
+        const rows = await this.json(SITE[provider], 'whoami', [], signal);
+        const identity = stringField(rows[0], 'identity');
+        if (!identity)
+            throw new OpenCliError(`${provider} returned no stable account identity`, 'PROVIDER_NOT_LOGGED_IN');
+        return createHash('sha256').update(`${provider}\0${identity}`).digest('hex');
+    }
+    /**
+     * List a provider's conversations.
+     * @param provider - which provider to list.
+     * @param signal - cancellation from the caller.
+     * @param since - ISO instant the adapter may stop paging at. Best-effort:
+     * adapters that page in an order they cannot vouch for ignore it, and one
+     * installed before the flag existed is retried without it rather than
+     * failing the pass.
+     * @returns the listed conversations.
+     */
+    async history(provider, signal, since = '') {
+        const rows = await this.historyRows(provider, since, signal);
+        return conversationRows(provider, rows);
+    }
+    /** Resolve account identity and history through one OpenCLI browser command. */
+    async syncIndex(provider, signal, since = '', accountScope = '') {
+        const args = [...(since ? ['--since', since] : []), ...(accountScope ? ['--accountScope', accountScope] : [])];
+        const rows = await this.json(SITE[provider], 'sync-index', args, signal);
+        const identity = rows.find(row => stringField(row, 'kind') === 'identity');
+        const stableIdentity = stringField(identity, 'identity');
+        if (!stableIdentity)
+            throw new OpenCliError(`${provider} returned no stable account identity`, 'PROVIDER_NOT_LOGGED_IN');
+        return {
+            accountScope: createHash('sha256').update(`${provider}\0${stableIdentity}`).digest('hex'),
+            sinceApplied: stringField(identity, 'sinceApplied'),
+            rows: conversationRows(provider, rows.filter(row => stringField(row, 'kind') === 'conversation')),
+        };
+    }
+    async detail(provider, id, signal, accountScope = '') {
+        const rows = await this.json(SITE[provider], 'detail', [id, ...(accountScope ? ['--accountScope', accountScope] : [])], signal);
+        return rows.map((raw, index) => {
+            const role = stringField(raw, 'role');
+            if (role !== 'user' && role !== 'assistant')
+                throw new OpenCliError('provider detail returned an invalid role', 'OPENCLI_CONFIGURATION');
+            return {
+                conversationId: required(raw, 'conversationId'), ordinal: integerField(raw, 'ordinal', index),
+                messageId: stringField(raw, 'messageId'), parentId: stringField(raw, 'parentId'),
+                branchId: stringField(raw, 'branchId'), activeBranch: booleanField(raw, 'activeBranch', true),
+                role, text: stringField(raw, 'text'), createdAt: stringField(raw, 'createdAt'),
+                attachmentsJson: stringField(raw, 'attachmentsJson', '[]'), partial: booleanField(raw, 'partial'),
+            };
+        });
+    }
+    async attachment(provider, locator, output, maxBytes, signal) {
+        const rows = await this.json(SITE[provider], 'attachment', [locator, '--output', output, '--maxBytes', String(maxBytes)], signal);
+        return rows[0] ?? {};
+    }
+    async health(signal) {
+        const [version, daemon, plugins, doctor] = await Promise.all([
+            this.probe(['--version'], signal), this.probe(['daemon', 'status'], signal), this.probe(['plugin', 'list'], signal),
+            this.probe(['doctor'], signal),
+        ]);
+        const status = parseDaemonStatus(daemon.value);
+        const cliVersion = normalizeVersion(version.value);
+        const daemonVersion = daemon.value.match(/^Version:\s+v?([^\s(]+)/m)?.[1];
+        const pluginVersion = plugins.value.match(/dsh-chat-history\s+@([^\s—]+)/i)?.[1];
+        const pluginInstalled = /dsh-chat-history/i.test(plugins.value);
+        const adapterCommandsReady = REQUIRED_ADAPTER_COMMANDS.every(command => new RegExp(`\\b${command}\\b`, 'i').test(plugins.value));
+        const opencliCompatible = versionAtLeast(cliVersion, MIN_OPENCLI_VERSION);
+        const daemonStale = Boolean(status.daemonRunning && (!daemonVersion || normalizeVersion(daemonVersion) !== cliVersion));
+        const connectivityOk = /\[OK\]\s+Connectivity:/i.test(doctor.value);
+        return {
+            version: cliVersion, daemon: daemon.value.trim(), pluginInstalled,
+            daemonRunning: status.daemonRunning, extensionConnected: status.extensionConnected, extensionState: status.extensionState,
+            opencliCompatible, daemonStale, connectivityOk,
+            ...(status.extensionVersion ? { extensionVersion: status.extensionVersion } : {}),
+            ...(status.profileCount !== undefined ? { profileCount: status.profileCount } : {}),
+            ...(daemonVersion ? { daemonVersion: normalizeVersion(daemonVersion) } : {}),
+            ...(pluginVersion ? { pluginVersion: normalizeVersion(pluginVersion) } : {}),
+            adapterCommandsReady,
+            adapterCompatible: pluginInstalled && adapterCommandsReady && versionAtLeast(pluginVersion ?? '', MIN_ADAPTER_VERSION),
+            ...(version.error ? { versionError: version.error } : {}),
+            ...(daemon.error ? { daemonError: daemon.error } : {}),
+            ...(plugins.error ? { pluginError: plugins.error } : {}),
+            ...(doctor.error ? { doctorError: doctor.error } : {}),
+        };
+    }
+    /** Lightweight executable validation used by automatic path discovery. */
+    async version(signal) { return normalizeVersion(await this.raw(['--version'], signal)); }
+    /** Confirm the executable also exposes OpenCLI's plugin command, not merely a semver-looking --version. */
+    async verifyInstallation(signal) { await this.raw(['plugin', 'list'], signal); }
+    async profiles(signal) {
+        const output = await this.raw(['profile', 'list'], signal);
+        const disconnected = output.indexOf('Disconnected saved profiles:');
+        return output.split(/\r?\n/).flatMap((line) => {
+            const match = line.match(/^\s{2}([A-Za-z0-9_-]+)(?:\s+([A-Za-z0-9_-]+))?(?:\s+default)?\s+—\s+(connected|not connected)/);
+            if (!match)
+                return [];
+            const position = output.indexOf(line);
+            return [{ id: match[1], ...(match[2] && match[2] !== 'default' ? { alias: match[2] } : {}),
+                    connected: match[3] === 'connected' && (disconnected < 0 || position < disconnected), isDefault: /\sdefault\s+—/.test(line) }];
+        });
+    }
+    async installPlugin(pluginUrl, signal) {
+        await this.raw(['plugin', 'install', pluginUrl], signal);
+    }
+    async restartDaemon(signal) { await this.raw(['daemon', 'restart'], signal); }
+    async probe(args, signal) {
+        try {
+            return { value: await this.raw(args, signal) };
+        }
+        catch (error) {
+            return { value: '', error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async historyRows(provider, since, signal) {
+        if (!since)
+            return this.json(SITE[provider], 'history-all', [], signal);
+        try {
+            return await this.json(SITE[provider], 'history-all', ['--since', since], signal);
+        }
+        catch (error) {
+            // An adapter installed before `--since` existed rejects the flag as a
+            // configuration error. Walking the whole history is slower but correct,
+            // and beats failing every background pass until the user remembers to
+            // reinstall the OpenCLI plugin.
+            if (!(error instanceof OpenCliError) || error.code !== 'OPENCLI_CONFIGURATION')
+                throw error;
+            return this.json(SITE[provider], 'history-all', [], signal);
+        }
+    }
+    async json(site, operation, args, signal) {
+        // Pin adapter traffic to a background tab. OpenCLI otherwise lets the
+        // process-wide OPENCLI_WINDOW environment variable override the adapter's
+        // defaultWindowMode, which could make an unattended sync steal focus.
+        const stdout = await this.raw([site, operation, ...args, '--window', 'background', '-f', 'json'], signal);
+        try {
+            const parsed = JSON.parse(stdout);
+            if (!Array.isArray(parsed) || parsed.some(row => !row || typeof row !== 'object' || Array.isArray(row)))
+                throw new Error('expected object array');
+            return parsed;
+        }
+        catch (error) {
+            throw new OpenCliError('OpenCLI returned malformed JSON', 'OPENCLI_CONFIGURATION', { cause: error });
+        }
+    }
+    async raw(args, signal) {
+        const invocation = resolveInvocation(this.executable);
+        const fullArgs = [...invocation.prefix, ...this.prefixArgs, ...(this.profile ? ['--profile', this.profile] : []), ...args];
+        try {
+            const result = await execFile(invocation.file, fullArgs, {
+                encoding: 'utf8', timeout: this.timeoutMs, maxBuffer: this.maxStdoutBytes,
+                windowsHide: true, shell: false, signal, env: { ...process.env, OPENCLI_WINDOW: 'background' },
+            });
+            return result.stdout;
+        }
+        catch (error) {
+            const detail = error;
+            if (detail.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+                throw new OpenCliError('OpenCLI output exceeded the configured limit', 'OPENCLI_OUTPUT_TOO_LARGE', { cause: error });
+            if (detail.killed || detail.signal === 'SIGTERM')
+                throw new OpenCliError('OpenCLI provider request timed out', 'PROVIDER_TIMEOUT', { cause: error });
+            const stderr = String(detail.stderr || detail.stdout || '').trim().slice(0, 2_000);
+            const exit = typeof detail.code === 'number' ? detail.code : undefined;
+            const code = stderr.includes('DSH_ACCOUNT_SCOPE_MISMATCH') ? 'PROVIDER_ACCOUNT_MISMATCH'
+                : exit === 69 ? 'EXTENSION_NOT_CONNECTED' : exit === 75 ? 'PROVIDER_TIMEOUT'
+                    : exit === 77 ? 'PROVIDER_NOT_LOGGED_IN' : exit === 78 ? 'OPENCLI_CONFIGURATION' : 'OPENCLI_FAILED';
+            throw new OpenCliError(stderr || `OpenCLI exited with ${String(detail.code)}`, code, { cause: error });
+        }
+    }
+}
+/** Locate a working OpenCLI without asking a command-line newcomer for PATH details. */
+export async function discoverOpenCli(configured = 'opencli', signal) {
+    const candidates = openCliCandidates(configured);
+    let lastError = '';
+    for (const executable of candidates) {
+        try {
+            const runner = new OpenCliRunner({ executable, timeoutMs: 15_000 });
+            const version = await runner.version(signal);
+            await runner.verifyInstallation(signal);
+            if (version)
+                return { found: true, executable, version };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    return { found: false, executable: configured, version: '', ...(lastError ? { error: lastError } : {}) };
+}
+/** Install or upgrade the supported OpenCLI package through this Node runtime's npm. */
+export async function installOpenCli(signal) {
+    const npm = resolveNpmInvocation();
+    if (!npm) {
+        throw new OpenCliError('npm was not found next to the Node.js runtime; install Node.js/npm, then retry', 'OPENCLI_INSTALL_FAILED');
+    }
+    try {
+        await execFile(npm.file, [...npm.prefix, 'install', '--global', `${OPENCLI_NPM_PACKAGE}@>=${MIN_OPENCLI_VERSION}`], {
+            encoding: 'utf8', timeout: 5 * 60_000, maxBuffer: 8 * 1024 * 1024,
+            windowsHide: true, shell: false, signal,
+        });
+    }
+    catch (error) {
+        const detail = error;
+        const output = String(detail.stderr || detail.stdout || '').trim().slice(0, 2_000);
+        throw new OpenCliError(output || 'npm could not install OpenCLI globally', 'OPENCLI_INSTALL_FAILED', { cause: error });
+    }
+    const discovery = await discoverOpenCli('opencli', signal);
+    if (!discovery.found)
+        throw new OpenCliError(discovery.error || 'OpenCLI was installed but could not be located', 'OPENCLI_INSTALL_FAILED');
+    return discovery;
+}
+function openCliCandidates(configured) {
+    const candidates = [configured, 'opencli'];
+    const prefix = process.env.npm_config_prefix;
+    if (process.platform === 'win32') {
+        if (process.env.APPDATA)
+            candidates.push(join(process.env.APPDATA, 'npm', 'opencli.cmd'));
+        if (prefix)
+            candidates.push(join(prefix, 'opencli.cmd'));
+    }
+    else {
+        if (prefix)
+            candidates.push(join(prefix, 'bin', 'opencli'));
+        candidates.push('/usr/local/bin/opencli', '/opt/homebrew/bin/opencli');
+    }
+    return [...new Set(candidates.filter(Boolean))];
+}
+function resolveNpmInvocation() {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && existsSync(npmExecPath)) {
+        return /\.(?:c?js|mjs)$/i.test(npmExecPath)
+            ? { file: process.execPath, prefix: [npmExecPath] }
+            : { file: npmExecPath, prefix: [] };
+    }
+    const besideNode = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(besideNode))
+        return { file: process.execPath, prefix: [besideNode] };
+    if (process.platform !== 'win32')
+        return { file: 'npm', prefix: [] };
+    return undefined;
+}
+function normalizeVersion(value) { return value.trim().replace(/^v/i, '').split(/\s+/)[0] ?? ''; }
+/** Numeric semver comparison for the stable x.y.z versions OpenCLI publishes. */
+export function versionAtLeast(value, minimum) {
+    const parse = (input) => normalizeVersion(input).split('.').slice(0, 3).map(part => Number.parseInt(part, 10));
+    const actual = parse(value);
+    const required = parse(minimum);
+    if (actual.length < 3 || actual.some(Number.isNaN))
+        return false;
+    for (let index = 0; index < 3; index++) {
+        const left = actual[index] ?? 0;
+        const right = required[index] ?? 0;
+        if (left !== right)
+            return left > right;
+    }
+    return true;
+}
+function resolveInvocation(configured) {
+    const explicit = resolve(configured);
+    if (/\.cmd$/i.test(configured) && existsSync(explicit)) {
+        const entry = join(explicit, '..', 'node_modules', '@jackwener', 'opencli', 'dist', 'src', 'main.js');
+        if (existsSync(entry))
+            return { file: process.execPath, prefix: [entry] };
+    }
+    if (process.platform === 'win32' && configured === 'opencli') {
+        const entry = process.env.APPDATA && join(process.env.APPDATA, 'npm', 'node_modules', '@jackwener', 'opencli', 'dist', 'src', 'main.js');
+        if (entry && existsSync(entry))
+            return { file: process.execPath, prefix: [entry] };
+    }
+    return { file: configured, prefix: [] };
+}
+function stringField(row, key, fallback = '') {
+    const value = row?.[key];
+    return value === undefined || value === null ? fallback : String(value);
+}
+function conversationRows(provider, rows) {
+    return rows.map(raw => ({
+        provider,
+        accountScope: '',
+        id: required(raw, 'id'), title: required(raw, 'title'), url: required(raw, 'url'),
+        createdAt: stringField(raw, 'createdAt'), updatedAt: stringField(raw, 'updatedAt'),
+        messageCount: integerField(raw, 'messageCount'), cursor: stringField(raw, 'cursor'),
+        partial: booleanField(raw, 'partial'),
+    }));
+}
+function required(row, key) {
+    const value = stringField(row, key).trim();
+    if (!value)
+        throw new OpenCliError(`provider row is missing ${key}`, 'OPENCLI_CONFIGURATION');
+    return value;
+}
+function integerField(row, key, fallback = 0) {
+    const value = Number(row[key] ?? fallback);
+    return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : fallback;
+}
+function booleanField(row, key, fallback = false) {
+    const value = row[key];
+    if (value === undefined)
+        return fallback;
+    return value === true || value === 'true' || value === 1 || value === '1';
+}

package/lib/reference.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Expands reference mentions in a user's prompt into untrusted background.
+ *
+ * This runs at the loop's pre-step boundary rather than at prompt submission,
+ * because submission is owned by each host and has no extension point, while
+ * pre-step is shared by every surface — Web, headless, ACP, scheduled runs,
+ * and subagents all pass through it. Whatever this listener returns is what
+ * the loop durably appends, so injected material is logged by construction and
+ * a replay reconstructs the request exactly.
+ *
+ * Two schemes are expanded. `dsh-ref:` names material outside the harness and
+ * is resolved through `ctx.references`. `dsh-session:` names another harness
+ * session and is delegated to `ctx.sessionReferenceResolver`, which owns
+ * session-surface semantics — compaction folding, shadowed events, cited event
+ * seqs — that do not generalize to an outside conversation.
+ *
+ * @module dsh-reference-anything/reference
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "reference-mention";
+/** The registry this expander reads through. */
+export declare const inject: string[];
+/** Upper bound on distinct references in one message, whatever the config says. */
+export declare const MAX_REFERENCES = 3;
+/** Deployment settings for mention expansion. */
+export interface Config {
+    /**
+     * Distinct `dsh-ref:` references honored in one message. Capped at
+     * {@link MAX_REFERENCES}: past a few sources the background stops being
+     * background, and the byte budget multiplies by the same factor.
+     */
+    maxReferences?: number;
+    /**
+     * Also expand `dsh-session:` mentions. Deployments that deliberately do not
+     * mount the cross-session resolver set this false, so such a mention is
+     * refused as unsupported rather than probed for on every message.
+     */
+    serveSessionScheme?: boolean;
+}
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * Register the pre-step mention expander.
+ * @param ctx - the mounting context.
+ * @param config - validated deployment settings.
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/reference.js

@@ -0,0 +1,228 @@
+/**
+ * Expands reference mentions in a user's prompt into untrusted background.
+ *
+ * This runs at the loop's pre-step boundary rather than at prompt submission,
+ * because submission is owned by each host and has no extension point, while
+ * pre-step is shared by every surface — Web, headless, ACP, scheduled runs,
+ * and subagents all pass through it. Whatever this listener returns is what
+ * the loop durably appends, so injected material is logged by construction and
+ * a replay reconstructs the request exactly.
+ *
+ * Two schemes are expanded. `dsh-ref:` names material outside the harness and
+ * is resolved through `ctx.references`. `dsh-session:` names another harness
+ * session and is delegated to `ctx.sessionReferenceResolver`, which owns
+ * session-surface semantics — compaction folding, shadowed events, cited event
+ * seqs — that do not generalize to an outside conversation.
+ *
+ * @module dsh-reference-anything/reference
+ */
+import z from '@deepseek-ai/schemastery';
+import { boundContextSummary, createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm';
+import { SESSION_REFERENCE_SCHEME, parseSessionReferenceText, } from '@deepseek-ai/dsh-session-reference';
+import { ReferenceAnythingError } from "./errors.js";
+import { renderDeferredReferences } from "./render.js";
+import { mayContainReference, parseReferenceText } from "./uri.js";
+import { WORKSPACE_REFERENCE_SCHEME, parseWorkspaceReferenceText, renderWorkspaceReferences } from "./workspace.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'reference-mention';
+/** The registry this expander reads through. */
+export const inject = ['references'];
+/** Upper bound on distinct references in one message, whatever the config says. */
+export const MAX_REFERENCES = 3;
+/** Runtime schema for {@link Config}. */
+export const Config = z.object({
+    maxReferences: z.number().step(1).min(1).max(MAX_REFERENCES).default(MAX_REFERENCES),
+    serveSessionScheme: z.boolean().default(true),
+});
+/**
+ * Register the pre-step mention expander.
+ * @param ctx - the mounting context.
+ * @param config - validated deployment settings.
+ */
+export function apply(ctx, config = {}) {
+    const maxReferences = Math.min(config.maxReferences ?? MAX_REFERENCES, MAX_REFERENCES);
+    const serveSessionScheme = config.serveSessionScheme ?? true;
+    ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject' || signal.aborted)
+            return decision;
+        // The overwhelmingly common case is a prompt with no mentions at all, and
+        // this runs on every step of every turn. Screening with substring scans
+        // before any parsing keeps that case free.
+        const target = decision.messages.findIndex(candidate => candidate.source.kind === 'user' && messageText(candidate).some(text => mentions(text, serveSessionScheme)));
+        if (target < 0)
+            return decision;
+        const original = decision.messages[target];
+        if (original === undefined)
+            return decision;
+        let parsed;
+        try {
+            parsed = parseMessage(original, serveSessionScheme);
+        }
+        catch (error) {
+            // A malformed URI inside an explicit mention is the user asking for
+            // something that does not exist. Saying so beats sending a prompt whose
+            // reference silently resolves to nothing.
+            return entered(decision, target, [notice(describe(error))], original);
+        }
+        if (parsed.references.length === 0 && parsed.sessionReferences.length === 0 && parsed.workspaceReferences.length === 0)
+            return decision;
+        let contexts;
+        try {
+            contexts = await resolve(ctx, agent, parsed, { maxReferences, serveSessionScheme }, signal);
+        }
+        catch (error) {
+            if (signal.aborted)
+                return decision;
+            contexts = [notice(describe(error))];
+        }
+        if (signal.aborted)
+            return decision;
+        return entered(decision, target, contexts, parsed.message);
+    }, { prepend: true });
+}
+/**
+ * Authorize and render the named references without reading their bodies.
+ * The agent decides whether the current request warrants `reference_read`.
+ */
+async function resolve(ctx, agent, parsed, limits, signal) {
+    const contexts = [];
+    if (parsed.workspaceReferences.length > 0) {
+        contexts.push(createUserMessage({
+            content: [{ type: 'text', text: await renderWorkspaceReferences(agent, parsed.workspaceReferences) }],
+            source: { kind: 'plugin', plugin: name, form: 'recall' },
+        }));
+    }
+    if (parsed.sessionReferences.length > 0) {
+        const resolver = ctx.get('sessionReferenceResolver');
+        if (resolver === undefined) {
+            throw new ReferenceAnythingError('this deployment cannot reference other harness sessions: the cross-session resolver is not mounted', 'SOURCE_UNAVAILABLE');
+        }
+        const prepared = await resolver.prepare(agent, contentOf(parsed.message), [...parsed.sessionReferences], signal);
+        if (prepared.additionalContext !== undefined)
+            contexts.push(prepared.additionalContext);
+    }
+    if (parsed.references.length > 0) {
+        const inputs = dedupe(parsed.references);
+        if (inputs.length > limits.maxReferences) {
+            throw new ReferenceAnythingError(`a message may reference at most ${limits.maxReferences} outside conversation`
+                + `${limits.maxReferences === 1 ? '' : 's'}; this one named ${inputs.length}`, 'REFERENCE_TOO_MANY');
+        }
+        for (const input of inputs)
+            ctx.references.grant(String(agent.session.id), input.ref);
+        const rendered = renderDeferredReferences(inputs);
+        contexts.push(createUserMessage({
+            content: [{ type: 'text', text: rendered.text }],
+            source: {
+                kind: 'reference-anything',
+                form: 'recall',
+                version: 1,
+                references: rendered.provenance,
+            },
+        }));
+    }
+    return contexts;
+}
+/**
+ * Replace the claimed message and place the background immediately before it.
+ *
+ * Adjacency is the point: background is only meaningful next to the prompt
+ * that named it, and the prompt stays last so it sits closest to the model's
+ * answer.
+ */
+function entered(decision, target, contexts, message) {
+    const replaced = decision.messages.with(target, message);
+    return { kind: 'enter', messages: replaced.toSpliced(target, 0, ...contexts) };
+}
+/** Rewrite both schemes' mentions to readable text, preserving message identity. */
+function parseMessage(message, serveSessionScheme) {
+    const references = [];
+    const sessionReferences = [];
+    const workspaceReferences = [];
+    let changed = false;
+    const content = message.content.map((block) => {
+        if (block.type !== 'text')
+            return block;
+        const own = parseReferenceText(block.text);
+        references.push(...own.references);
+        let text = own.text;
+        if (text.includes(WORKSPACE_REFERENCE_SCHEME)) {
+            const workspace = parseWorkspaceReferenceText(text);
+            workspaceReferences.push(...workspace.references);
+            text = workspace.text;
+        }
+        if (serveSessionScheme && text.includes(SESSION_REFERENCE_SCHEME)) {
+            const session = parseSessionReferenceText(text);
+            sessionReferences.push(...session.references);
+            text = session.text;
+        }
+        if (text === block.text)
+            return block;
+        changed = true;
+        return { ...block, text };
+    });
+    // freezeMessage keeps the existing identity: the loop claimed this message
+    // by id, so minting a new one would log something the inbox never claimed.
+    return {
+        message: changed ? freezeMessage({ ...message, content }) : message,
+        references,
+        sessionReferences,
+        workspaceReferences,
+    };
+}
+/** First-appearance order, one entry per distinct reference. */
+function dedupe(references) {
+    const seen = new Set();
+    const unique = [];
+    for (const reference of references) {
+        const key = JSON.stringify([reference.ref.source, reference.ref.id]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(reference);
+    }
+    return unique;
+}
+function mentions(text, serveSessionScheme) {
+    return mayContainReference(text) || text.includes(WORKSPACE_REFERENCE_SCHEME) || (serveSessionScheme && text.includes(SESSION_REFERENCE_SCHEME));
+}
+function messageText(message) {
+    return message.content.flatMap(block => block.type === 'text' ? [block.text] : []);
+}
+function contentOf(message) {
+    return message.content.map(block => ({ ...block }));
+}
+function notice(summary) {
+    return createUserMessage({
+        content: [{
+                type: 'text',
+                text: `A conversation reference in the previous message could not be resolved: ${summary}`,
+            }],
+        source: {
+            kind: 'plugin',
+            plugin: name,
+            form: 'notice',
+            summary: boundContextSummary(summary),
+        },
+    });
+}
+/**
+ * Flatten an error and its causes into one line for the user.
+ *
+ * The outer error names which reference failed; the cause names why, and why
+ * is the actionable half — "the browser is closed" tells someone what to do
+ * where "failed to read chat.json" does not. Bounded in depth so a long
+ * provider chain cannot crowd out the message.
+ */
+function describe(error) {
+    const parts = [];
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error && !seen.has(current) && parts.length < 3) {
+        seen.add(current);
+        const code = current instanceof ReferenceAnythingError ? `${current.code} — ` : '';
+        parts.push(`${code}${current.message}`);
+        current = current.cause;
+    }
+    return parts.length === 0 ? String(error) : parts.join(': ');
+}