dsh-dlp 0.1.0 → 0.3.0

package/lib/cli.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * `dsh-dlp report` — read this plugin's audit JSONL and say what it decided.
+ *
+ * The sink is the only evidence a decision happened, and nothing read it: a
+ * user could not answer "what did this block today?". This command reads the
+ * file directly and imports nothing from the harness, so it runs wherever the
+ * package is installed, with no profile and no `dsh` on the path.
+ *
+ * The file is a durable boundary — written by an older version of this
+ * package, appended to under crash — so every line is parsed defensively and a
+ * line that is not a record is counted rather than trusted.
+ * @module dsh-dlp/cli
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { defaultAuditLog } from "./home.js";
+/** Decision kinds that stopped a call, as opposed to rewriting its result. */
+const DENYING_KINDS = new Set(['guard-deny', 'pre-execute-deny', 'execution-mutation']);
+/** How many decisions the report lists individually. */
+const RECENT_LIMIT = 10;
+/** Read one string field, or `undefined` when the line does not carry it. */
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Rule ids named by a record's spans, in file order and without repeats. */
+function ruleIdsOf(record) {
+    const spans = record['spans'];
+    if (!Array.isArray(spans))
+        return [];
+    const ids = spans.flatMap((span) => {
+        if (typeof span !== 'object' || span === null)
+            return [];
+        const ruleId = span['ruleId'];
+        return typeof ruleId === 'string' ? [ruleId] : [];
+    });
+    return [...new Set(ids)];
+}
+/** Invisible-character counts a record carries, keeping only numeric entries. */
+function unicodeOf(record) {
+    const counts = record['unicode'];
+    if (typeof counts !== 'object' || counts === null || Array.isArray(counts))
+        return {};
+    return Object.fromEntries(Object.entries(counts).flatMap(([key, value]) => typeof value === 'number' ? [[key, value]] : []));
+}
+/**
+ * Parse one JSONL line into the fields this command reports on.
+ * @param line - one line of the audit file.
+ * @returns the record, or `undefined` when the line is not one.
+ */
+export function parseRecord(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        // A torn final line from an interrupted append is the expected cause.
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    const kind = stringField(record, 'kind');
+    const written = stringField(record, 'time');
+    if (kind === undefined || written === undefined)
+        return undefined;
+    const time = Date.parse(written);
+    if (Number.isNaN(time))
+        return undefined;
+    const tool = stringField(record, 'tool');
+    const sessionId = stringField(record, 'sessionId');
+    return {
+        time,
+        kind,
+        ...tool === undefined ? {} : { tool },
+        ...sessionId === undefined ? {} : { sessionId },
+        ruleIds: ruleIdsOf(record),
+        unicode: unicodeOf(record),
+    };
+}
+/** Text printed for `--help` and alongside a usage error. */
+export const USAGE = [
+    'Usage: dsh-dlp report [options]',
+    '',
+    'Reads the JSONL audit sink this plugin writes and summarises what it decided.',
+    '',
+    'Options:',
+    '  --log <path>     audit file to read (default: $DSH_HOME/dsh-dlp.audit.jsonl)',
+    '  --since <when>   only decisions at or after an ISO timestamp, or a span back',
+    '                   from now written as 30m, 24h or 7d',
+    '  --session <id>   only decisions from one session',
+    '  --would-have     only the decisions that let the call through: the redactions',
+    '                   and invisible-character findings, which is what a policy that',
+    '                   denied instead of rewriting would have blocked',
+    '  -h, --help       print this text',
+].join('\n');
+/** Milliseconds in one `--since` suffix; {@link parseSince} accepts no other. */
+function spanUnitMs(unit) {
+    switch (unit) {
+        case 's': return 1000;
+        case 'm': return 60_000;
+        case 'h': return 3_600_000;
+        default: return 86_400_000;
+    }
+}
+/**
+ * Read `--since`: an ISO timestamp, or a span back from now.
+ * @param value - the argument as written.
+ * @param now - epoch milliseconds a relative span counts back from.
+ * @returns epoch milliseconds, or `undefined` when the value is neither.
+ */
+export function parseSince(value, now) {
+    if (/^\d+[smhd]$/.test(value))
+        return now - Number(value.slice(0, -1)) * spanUnitMs(value.slice(-1));
+    const absolute = Date.parse(value);
+    return Number.isNaN(absolute) ? undefined : absolute;
+}
+/**
+ * Read the command line.
+ * @param argv - arguments after the program name.
+ * @param env - environment used for the default sink path.
+ * @param now - epoch milliseconds a relative `--since` counts back from.
+ * @returns what to run, or the usage error to print.
+ */
+export function parseArguments(argv, env, now) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '-h' || command === '--help')
+        return { kind: 'help' };
+    if (command !== 'report')
+        return { kind: 'error', message: `dsh-dlp: unknown command ${JSON.stringify(command)}` };
+    let log = defaultAuditLog(env);
+    let since;
+    let session;
+    let wouldHave = false;
+    let consumed = false;
+    for (const [index, flag] of rest.entries()) {
+        if (consumed) {
+            consumed = false;
+            continue;
+        }
+        switch (flag) {
+            case '--log':
+            case '--since':
+            case '--session': {
+                const value = rest[index + 1];
+                if (value === undefined)
+                    return { kind: 'error', message: `dsh-dlp: ${flag} needs a value` };
+                consumed = true;
+                if (flag === '--log')
+                    log = value;
+                else if (flag === '--session')
+                    session = value;
+                else {
+                    const parsed = parseSince(value, now);
+                    if (parsed === undefined) {
+                        return {
+                            kind: 'error',
+                            message: `dsh-dlp: --since ${JSON.stringify(value)} is neither a timestamp nor a span like 24h`,
+                        };
+                    }
+                    since = parsed;
+                }
+                break;
+            }
+            case '--would-have':
+                wouldHave = true;
+                break;
+            case '-h':
+            case '--help':
+                return { kind: 'help' };
+            default:
+                return { kind: 'error', message: `dsh-dlp: unknown option ${JSON.stringify(flag)}` };
+        }
+    }
+    return {
+        kind: 'report',
+        options: {
+            log,
+            ...since === undefined ? {} : { since },
+            ...session === undefined ? {} : { session },
+            wouldHave,
+        },
+    };
+}
+/**
+ * Read and parse the audit file.
+ * @param path - the file to read.
+ * @returns its records, its absence, or the problem to print.
+ */
+export function readAuditFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'absent' };
+        return { kind: 'unreadable', problem: `dsh-dlp: cannot read ${path}: ${String(error)}` };
+    }
+    const lines = text.split('\n').filter(line => line.trim().length > 0);
+    const records = lines.flatMap((line) => {
+        const record = parseRecord(line);
+        return record === undefined ? [] : [record];
+    });
+    return { kind: 'read', records, unreadable: lines.length - records.length };
+}
+/** Count each label over the records, most frequent first. */
+function tally(records, label) {
+    const counts = new Map();
+    for (const record of records) {
+        for (const key of label(record))
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+}
+/** One `name  count` line per entry, padded so the column lines up. */
+function countLines(entries) {
+    const width = Math.max(...entries.map(([name]) => name.length));
+    return entries.map(([name, count]) => `  ${name.padEnd(width)}  ${count}`);
+}
+/** A heading and its counts, or nothing when there are none. */
+function section(heading, entries) {
+    return entries.length === 0 ? [] : ['', heading, ...countLines(entries)];
+}
+/**
+ * Render the report.
+ * @param records - every record the file yielded.
+ * @param unreadable - how many of its lines were not records.
+ * @param options - the filters the invocation asked for.
+ * @returns the lines to print.
+ */
+export function formatReport(records, unreadable, options) {
+    const selected = records.filter((record) => {
+        if (options.since !== undefined && record.time < options.since)
+            return false;
+        if (options.session !== undefined && record.sessionId !== options.session)
+            return false;
+        if (options.wouldHave && DENYING_KINDS.has(record.kind))
+            return false;
+        return true;
+    });
+    const lines = [`dsh-dlp: ${selected.length} decision(s) in ${options.log}`];
+    if (options.since !== undefined)
+        lines.push(`  since ${new Date(options.since).toISOString()}`);
+    if (options.session !== undefined)
+        lines.push(`  session ${options.session}`);
+    if (options.wouldHave)
+        lines.push('  only decisions that let the call through');
+    if (unreadable > 0)
+        lines.push(`  ${unreadable} line(s) were not readable as records`);
+    if (selected.length === 0)
+        return lines;
+    lines.push(...section('by decision', tally(selected, record => [record.kind])), ...section('by rule', tally(selected, record => record.ruleIds)), ...section('by tool', tally(selected, record => record.tool === undefined ? [] : [record.tool])), ...section('results carrying invisible characters', tally(selected, record => Object.keys(record.unicode))));
+    const recent = [...selected].sort((left, right) => right.time - left.time).slice(0, RECENT_LIMIT);
+    lines.push('', `most recent ${recent.length}`);
+    for (const record of recent) {
+        const rules = record.ruleIds.length === 0 ? '-' : record.ruleIds.join(', ');
+        lines.push(`  ${new Date(record.time).toISOString()}  ${record.kind}  ${record.tool ?? '-'}  ${rules}`);
+    }
+    return lines;
+}
+/**
+ * Run one invocation.
+ * @param argv - arguments after the program name.
+ * @param write - receives each line of output.
+ * @param fail - receives each line of error output.
+ * @param env - environment used for the default sink path.
+ * @param now - epoch milliseconds a relative `--since` counts back from.
+ * @returns the process exit code.
+ */
+export function main(argv, write, fail, env = process.env, now = Date.now()) {
+    const invocation = parseArguments(argv, env, now);
+    if (invocation.kind === 'help') {
+        write(USAGE);
+        return 0;
+    }
+    if (invocation.kind === 'error') {
+        fail(invocation.message);
+        fail(USAGE);
+        return 2;
+    }
+    const file = readAuditFile(invocation.options.log);
+    switch (file.kind) {
+        case 'absent':
+            write(`dsh-dlp: no audit file at ${invocation.options.log}`);
+            write('Nothing has been recorded yet, or the deployment set `auditLog` elsewhere — pass --log <path>.');
+            return 0;
+        case 'unreadable':
+            fail(file.problem);
+            return 1;
+        case 'read':
+            for (const line of formatReport(file.records, file.unreadable, invocation.options))
+                write(line);
+            return 0;
+        /* v8 ignore next 4 -- unreachable while `AuditFileRead` stays closed; the arm exists so adding a variant fails the build. */
+        default: {
+            const unhandled = file;
+            throw new TypeError(`dsh-dlp: unhandled audit file read ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/* v8 ignore start -- the process entry, exercised by tests/e2e/report.e2e.ts against the built CLI rather than by the instrumented unit run. */
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = main(process.argv.slice(2), line => process.stdout.write(`${line}\n`), line => process.stderr.write(`${line}\n`));
+}
+/* v8 ignore stop */

package/lib/detectors.js

@@ -58,11 +58,94 @@ export const SYNC_RULES = [
     { id: 'dsh-dlp/teams-webhook-url', version: 1, severity: 'critical', pattern: /\bhttps:\/\/[A-Za-z0-9.-]*webhook\.office\.com\/webhookb2\/[A-Za-z0-9@/_-]{10,}/g },
     { id: 'dsh-dlp/secret-assignment', version: 1, severity: 'medium', pattern: /\b(?:api[_-]?key|secret[_-]?key|client[_-]?secret|password|passwd|access[_-]?token|auth[_-]?token)\b\s*[=:]\s*["']?[A-Za-z0-9/+=_-]{16,}["']?/gi },
 ];
+/** Build one class's run pattern from its ranges, so the two cannot drift apart. */
+function unicodeRule(id, action, ranges) {
+    return { id, version: 1, severity: 'medium', action, ranges, pattern: new RegExp(`[${ranges}]+`, 'gu') };
+}
+/**
+ * Character classes that hide text from the reader while the model still reads
+ * it, verified against the Unicode character database.
+ *
+ * Every class is `medium`. These are injection *indicators*, not credentials:
+ * the guard floor denies at `high` and above, so an argument carrying one is
+ * never denied on that basis. What they buy is a redaction and an audit record
+ * on a path the harness does not cover — it strips directional controls in
+ * exactly one place, session titles, and never on the tool-result path.
+ *
+ * Not attempted here: UTS #39 confusables. A Cyrillic `а` needs a data table
+ * to detect and is a different cost class, and it defeats every rule in this
+ * file. README.md says so rather than implying coverage.
+ */
+export const UNICODE_RULES = [
+    // Tags block: a full ASCII alphabet with no rendering, the standard carrier
+    // for instructions meant for the model and not for the reader.
+    unicodeRule('dsh-dlp/unicode-tag-characters', 'strip', String.raw `\u{E0000}-\u{E007F}`),
+    // Bidi overrides and isolates reorder what is displayed without changing the
+    // characters a model reads.
+    unicodeRule('dsh-dlp/unicode-bidi-override', 'strip', String.raw `\u{202A}-\u{202E}\u{2066}-\u{2069}`),
+    // U+200D joins legitimate emoji sequences, so stripping this class has a
+    // real false positive.
+    unicodeRule('dsh-dlp/unicode-zero-width', 'report', String.raw `\u{200B}-\u{200D}\u{2060}\u{FEFF}`),
+    // Bidi marks, unlike the overrides above, appear in real right-to-left text.
+    unicodeRule('dsh-dlp/unicode-bidi-mark', 'report', String.raw `\u{061C}\u{200E}\u{200F}`),
+    unicodeRule('dsh-dlp/unicode-variation-selector', 'report', String.raw `\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}`),
+];
+/**
+ * One run of any indicator class. The scan is a single pass over the input
+ * with this pattern; the per-class patterns then run over the matched runs
+ * only, which are a handful of characters each.
+ */
+const UNICODE_RUN = new RegExp(`[${UNICODE_RULES.map(rule => rule.ranges).join('')}]+`, 'gu');
+/**
+ * Find every invisible or direction-changing character in one string.
+ *
+ * Offsets are UTF-16 indices into `text`, so a caller can splice them
+ * directly; they are exact rather than advisory, and {@link Detection.exact}
+ * says so.
+ * @param text - the string to scan.
+ * @returns every indicator run, ordered by start offset.
+ */
+export function scanUnicode(text) {
+    const findings = [];
+    for (const run of text.matchAll(UNICODE_RUN)) {
+        for (const rule of UNICODE_RULES) {
+            for (const match of run[0].matchAll(rule.pattern)) {
+                const start = run.index + match.index;
+                findings.push({
+                    ruleId: rule.id,
+                    ruleVersion: rule.version,
+                    severity: rule.severity,
+                    start,
+                    end: start + match[0].length,
+                    exact: true,
+                    action: rule.action,
+                });
+            }
+        }
+    }
+    findings.sort(byPosition);
+    return findings;
+}
+/**
+ * How many runs of each indicator class one string carries.
+ * @param text - the string to scan.
+ * @returns a count per rule id; absent means none were found.
+ */
+export function countUnicodeIndicators(text) {
+    const counts = {};
+    for (const finding of scanUnicode(text)) {
+        counts[finding.ruleId] = (counts[finding.ruleId] ?? 0) + 1;
+    }
+    return counts;
+}
 /**
  * Scan text with tier 1. Pure, synchronous, no I/O, and never capped: a table
  * of anchored regular expressions costs a linear pass, so there is no reason
  * to stop scanning where tier 2 has to. `truncated` is therefore always
  * `false` here and only tier 2 can set it.
+ *
+ * The `strip` half of {@link UNICODE_RULES} is included, so every seam reading
+ * tier 1 — including the synchronous telemetry waterfall — gets it.
  * @param text - the string to scan.
  * @param rules - the rule table to apply; defaults to {@link SYNC_RULES}.
  * @returns every match, ordered by start offset.
@@ -82,6 +165,10 @@ export function scanSync(text, rules = SYNC_RULES) {
             });
         }
     }
+    for (const finding of scanUnicode(text)) {
+        if (finding.action === 'strip')
+            detections.push(finding);
+    }
     detections.sort(byPosition);
     return { detections, truncated: false };
 }

package/lib/guard.js

@@ -27,7 +27,7 @@
  * @module dsh-dlp/guard
  */
 import { DENY_SEVERITY, scanSync, severityRank } from "./detectors.js";
-import { isEgressCapable, matchPathArgument, pathArguments, pathCandidates } from "./paths.js";
+import { isEgressCapable, matchPathArgument, pathArguments, pathCandidates, rulesForTool } from "./paths.js";
 import { nestedStrings } from "./redaction.js";
 /**
  * Denial text for a credential-path match.
@@ -57,20 +57,23 @@ function secretArgumentReason(toolName, ruleIds, hashes) {
  * Credential paths are denied for every tool, not only readers: a shell that
  * can `cat` a key can also copy it. Only path-typed arguments are tested —
  * running the table over every string matches file content and denies writing
- * a `.gitignore` that mentions `.env`. Argument secrets are denied only for
- * egress-capable tools, because denying a local editor for holding the text it
- * was asked to write would break ordinary work without closing an exfiltration
- * path.
+ * a `.gitignore` that mentions `.env`. The one exception is a `writes-only`
+ * rule, which a tool classified read-only is exempt from; that is how
+ * `$DSH_HOME` stays readable while every write to it is denied. Argument
+ * secrets are denied only for egress-capable tools, because denying a local
+ * editor for holding the text it was asked to write would break ordinary work
+ * without closing an exfiltration path.
  * @param exec - the pending call as the guard stage sees it.
  * @param policy - the effective policy after the tighten-only merge.
  * @param hasher - mints the keyed hashes quoted in a denial reason.
  * @returns the denial, or `undefined` to abstain.
  */
 export function evaluateGuard(exec, policy, hasher) {
+    const rules = rulesForTool(exec.name, policy.credentialPathRules);
     for (const argument of pathArguments(exec.arguments)) {
         const candidates = argument.shell ? pathCandidates(argument.text) : [argument.text];
         for (const candidate of candidates) {
-            const rule = matchPathArgument(candidate, policy.credentialPathRules);
+            const rule = matchPathArgument(candidate, rules);
             if (rule === undefined)
                 continue;
             const hash = hasher.hash(candidate);

package/lib/home.js

@@ -0,0 +1,37 @@
+/**
+ * Where the harness keeps its state, and where this plugin's audit sink lands
+ * by default.
+ *
+ * Its own module so the `dsh-dlp report` command can resolve the sink without
+ * importing the plugin: `policy.ts` pulls in `@secretlint/core`, `js-yaml` and
+ * the schema library, none of which a reader of a JSONL file needs.
+ * @module dsh-dlp/home
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * File name the bundle patch gives the audit sink under the harness home.
+ * `cordis.patch.yml` spells the same name; a deployment that sets `auditLog`
+ * itself must tell `dsh-dlp report` where it put it.
+ */
+export const DEFAULT_AUDIT_LOG_NAME = 'dsh-dlp.audit.jsonl';
+/**
+ * Resolve the harness home the same way the harness does: `$DSH_HOME` when it
+ * is set to something other than whitespace, otherwise `~/.dsh`. Read here
+ * rather than through `@deepseek-ai/dsh-home-paths` to keep the plugin's
+ * runtime imports to the ones a profile is guaranteed to resolve.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute harness home.
+ */
+export function resolveDshHome(env = process.env) {
+    const configured = env['DSH_HOME'];
+    return resolve(configured !== undefined && configured.trim().length > 0 ? configured : join(homedir(), '.dsh'));
+}
+/**
+ * Where the audit sink sits when the deployment did not name one.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute path the bundle patch configures.
+ */
+export function defaultAuditLog(env = process.env) {
+    return join(resolveDshHome(env), DEFAULT_AUDIT_LOG_NAME);
+}

package/lib/images.js

@@ -0,0 +1,183 @@
+/**
+ * Neutralising remote markdown images in assistant output, on the `llm/stream`
+ * waterfall.
+ *
+ * The web UI renders any absolute `http:`/`https:` markdown image a model
+ * emits as a real `<img src>`, and the harness sets no Content-Security-Policy,
+ * so the fetch happens in the user's browser where no host-side listener can
+ * see it. This module rewrites the destination out of the assistant's text
+ * before it becomes an `assistant/chunk` or `assistant/message` session event,
+ * so the log and the rendered answer stay in agreement.
+ *
+ * Two properties this module exists to hold:
+ *
+ * - **A destination split across chunks is still caught.** The mock and real
+ *   adapters both emit text in small deltas, so `![alt](https://host/x)` is
+ *   routinely spread over several of them and the browser renders the
+ *   accumulation. Text that could still be the start of an image is held back
+ *   until it either completes or exceeds {@link MAX_HELD_CHARACTERS}.
+ * - **Only the destination is replaced.** The alt text survives, so the
+ *   sentence the model wrote still reads, and the renderer's own
+ *   non-absolute-URL arm shows that alt text instead of fetching anything.
+ *
+ * This does not close the channel. It matches inline image syntax only:
+ * reference-style images, an alt text carrying a `]`, and any destination form
+ * the pattern does not model still reach the renderer. Raw HTML needs no
+ * handling — the renderer keeps it as literal text and no HTML enters the DOM
+ * (`packages/client/ui-primitives/src/markdown/render.tsx:261-263`). The
+ * upstream fix is one `img-src` directive.
+ * @module dsh-dlp/images
+ */
+/**
+ * Destination substituted for a remote image URL.
+ *
+ * It is deliberately not a URL: `new URL()` throws on it, which is the
+ * renderer's own "not an absolute destination" arm, and that arm renders the
+ * alt text as a `<span>` instead of emitting an `<img>`.
+ */
+export const BLOCKED_IMAGE_DESTINATION = 'dsh-dlp-blocked-remote-image';
+/**
+ * One inline image: alt text, destination, optional title.
+ *
+ * The destination is either an angle-bracketed form or a run of characters
+ * with no whitespace and no parenthesis, which is what CommonMark accepts
+ * without balanced-parenthesis nesting.
+ */
+const INLINE_IMAGE = /!\[([^\]]*)\]\(\s*(<[^<>\n]*>|[^\s()]*)((?:\s+(?:"[^"]*"|'[^']*'|\([^()]*\)))?)\s*\)/g;
+/**
+ * Text that could still become an inline image once more of the stream
+ * arrives: an alt text still open, a closed alt text followed by `(`, or a
+ * destination not yet closed.
+ */
+const PARTIAL_IMAGE = /^!\[[^\]]*(?:\](?:\((?:\s*(?:<[^<>\n]*|[^\s()]*))?)?)?$/;
+/**
+ * Longest suffix held back waiting for an image to complete.
+ *
+ * Held text is text the user cannot see yet, so the wait is bounded: past this
+ * many characters the suffix is emitted as it stands and a destination that
+ * completes later is caught only by the assembled block. A protocol bound on
+ * this module's own buffering, not a deployment choice.
+ */
+export const MAX_HELD_CHARACTERS = 4096;
+/**
+ * The hostname of an absolute `http(s)` destination.
+ * @param destination - the image destination exactly as the model wrote it.
+ * @returns the hostname, or `undefined` when the destination is not an absolute HTTP(S) URL.
+ */
+function remoteHost(destination) {
+    const trimmed = destination.startsWith('<') && destination.endsWith('>')
+        ? destination.slice(1, -1)
+        : destination;
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        // The only failure mode for a string: not an absolute URL, which the
+        // renderer also refuses, so there is nothing to neutralise.
+        return undefined;
+    }
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.hostname : undefined;
+}
+/**
+ * Replace every absolute HTTP(S) inline image destination in one string.
+ * @param text - assistant text, whole or partial.
+ * @returns the rewritten text and the hosts whose destinations were replaced.
+ */
+export function neutralizeRemoteImages(text) {
+    const hosts = [];
+    const rewritten = text.replace(INLINE_IMAGE, (match, alt, destination, title) => {
+        const host = remoteHost(destination);
+        if (host === undefined)
+            return match;
+        hosts.push(host);
+        return `![${alt}](${BLOCKED_IMAGE_DESTINATION}${title})`;
+    });
+    return { text: rewritten, hosts };
+}
+/**
+ * Where the held suffix of a partially streamed string starts.
+ * @param text - everything accumulated for one block and not yet emitted.
+ * @returns the offset to emit up to; the string's length when nothing is held.
+ */
+export function heldSuffixStart(text) {
+    const marker = text.lastIndexOf('![');
+    if (marker !== -1 && text.length - marker <= MAX_HELD_CHARACTERS && PARTIAL_IMAGE.test(text.slice(marker))) {
+        return marker;
+    }
+    return text.endsWith('!') ? text.length - 1 : text.length;
+}
+/**
+ * Wrap one model stream, replacing remote image destinations in its text.
+ *
+ * Text deltas are rewritten as they pass, with a possible image start held
+ * back until it resolves, and the assembled block on `block-end` — which is
+ * what the agent loop turns into the assistant message — is rewritten too. A
+ * held suffix is always flushed as a delta before the block closes and before
+ * the terminal finish, so no text is lost and the emitted chunks still satisfy
+ * the stream grammar.
+ * @param source - the stream from the rest of the waterfall.
+ * @param onNeutralized - notified once per host per text block.
+ * @returns the rewritten stream.
+ */
+export async function* neutralizeImageStream(source, onNeutralized) {
+    const held = new Map();
+    const reported = new Map();
+    /** Report each host once per block: the deltas and the assembled block carry the same text. */
+    const report = (index, hosts) => {
+        let seen = reported.get(index);
+        if (seen === undefined) {
+            seen = new Set();
+            reported.set(index, seen);
+        }
+        for (const host of hosts) {
+            if (seen.has(host))
+                continue;
+            seen.add(host);
+            onNeutralized(host);
+        }
+    };
+    /** Emit whatever one block is still holding, so a close or a finish loses nothing. */
+    function* flush(index) {
+        const pending = held.get(index);
+        held.delete(index);
+        if (pending !== undefined && pending.length > 0)
+            yield { type: 'text-delta', index, text: pending };
+    }
+    for await (const chunk of source) {
+        switch (chunk.type) {
+            case 'text-delta': {
+                const { text, hosts } = neutralizeRemoteImages((held.get(chunk.index) ?? '') + chunk.text);
+                report(chunk.index, hosts);
+                const cut = heldSuffixStart(text);
+                held.set(chunk.index, text.slice(cut));
+                if (cut > 0)
+                    yield { ...chunk, text: text.slice(0, cut) };
+                break;
+            }
+            case 'block-end': {
+                yield* flush(chunk.index);
+                if (chunk.block.type !== 'text') {
+                    yield chunk;
+                    break;
+                }
+                const { text, hosts } = neutralizeRemoteImages(chunk.block.text);
+                report(chunk.index, hosts);
+                yield text === chunk.block.text ? chunk : { ...chunk, block: { ...chunk.block, text } };
+                break;
+            }
+            case 'finish': {
+                for (const index of [...held.keys()])
+                    yield* flush(index);
+                yield chunk;
+                break;
+            }
+            default:
+                yield chunk;
+        }
+    }
+    // Only a stream that ended without a terminal finish reaches this: the
+    // grammar forbids emitting after one, so the flush above already ran.
+    for (const index of [...held.keys()])
+        yield* flush(index);
+}