@harborclient/core 0.1.1

package/dist/ai/scriptReferences.js

@@ -0,0 +1,787 @@
+const AI_SCRIPT_REFERENCE_UUID = '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
+/**
+ * Regex matching `@` script references in chat text:
+ * - Request scripts: `@<request-id>.<pre|post>.<script-index>`
+ * - Standalone snippets: `@snippet.<uuid>`
+ * - Footer terminals: `@term.<terminal-index>`
+ * - Collections: `@collection.<uuid>`
+ * - Folders: `@folder.<uuid>`
+ * - Saved requests: `@request.<uuid>`
+ * - Markdown documents and request comments: `@markdown.<uuid>`
+ * - Active request raw body: `@body`
+ *
+ * Request scripts, snippets, markdown, and raw body accept an optional
+ * `#<selection-start>.<selection-end>` suffix (character offsets). Terminal references use the
+ * same suffix for 1-based line numbers.
+ */
+export const AI_SCRIPT_REFERENCE_PATTERN = new RegExp(`@(?:(active|\\d+)\\.(pre|post)\\.(\\d+)|snippet\\.(${AI_SCRIPT_REFERENCE_UUID})|term\\.(\\d+)|collection\\.(${AI_SCRIPT_REFERENCE_UUID})|folder\\.(${AI_SCRIPT_REFERENCE_UUID})|request\\.(${AI_SCRIPT_REFERENCE_UUID})|markdown\\.(${AI_SCRIPT_REFERENCE_UUID})|(body))(?:#(\\d+)\\.(\\d+))?(?!\\d)`, 'g');
+/**
+ * Returns whether `@` at `index` is at a token boundary (start of text or after whitespace).
+ *
+ * @param text - Full composer draft.
+ * @param index - Index of the `@` character.
+ */
+function isScriptReferenceBoundary(text, index) {
+    if (index === 0) {
+        return true;
+    }
+    const previous = text[index - 1];
+    return previous != null && /\s/.test(previous);
+}
+/**
+ * Parses selection suffix groups from a regex match.
+ *
+ * @param selectionStartRaw - Captured selection start group.
+ * @param selectionEndRaw - Captured selection end group.
+ * @param lineRange - When true, requires 1-based line numbers with end >= start.
+ */
+function parseSelectionSuffix(selectionStartRaw, selectionEndRaw, lineRange = false) {
+    if (selectionStartRaw == null || selectionEndRaw == null) {
+        return undefined;
+    }
+    const selectionStart = Number(selectionStartRaw);
+    const selectionEnd = Number(selectionEndRaw);
+    if (!Number.isInteger(selectionStart) || !Number.isInteger(selectionEnd)) {
+        return undefined;
+    }
+    if (lineRange) {
+        if (selectionStart >= 1 && selectionEnd >= selectionStart) {
+            return { start: selectionStart, end: selectionEnd };
+        }
+        return undefined;
+    }
+    if (selectionStart >= 0 && selectionEnd > selectionStart) {
+        return { start: selectionStart, end: selectionEnd };
+    }
+    return undefined;
+}
+/**
+ * Parses one regex match into a structured script reference.
+ *
+ * @param match - RegExp match for {@link AI_SCRIPT_REFERENCE_PATTERN}.
+ * @param start - Document start offset of the match.
+ */
+export function parseAiScriptReferenceMatch(match, start) {
+    const text = match[0];
+    const requestIdRaw = match[1];
+    const phase = match[2];
+    const scriptIndexRaw = match[3];
+    const snippetUuid = match[4];
+    const terminalIndexRaw = match[5];
+    const collectionUuid = match[6];
+    const folderUuid = match[7];
+    const requestUuid = match[8];
+    const markdownUuid = match[9];
+    const bodyToken = match[10];
+    const selectionStartRaw = match[11];
+    const selectionEndRaw = match[12];
+    if (bodyToken != null) {
+        return {
+            kind: 'body',
+            start,
+            end: start + text.length,
+            text,
+            selection: parseSelectionSuffix(selectionStartRaw, selectionEndRaw)
+        };
+    }
+    if (collectionUuid != null) {
+        return {
+            kind: 'collection',
+            collectionUuid,
+            start,
+            end: start + text.length,
+            text
+        };
+    }
+    if (folderUuid != null) {
+        return {
+            kind: 'folder',
+            folderUuid,
+            start,
+            end: start + text.length,
+            text
+        };
+    }
+    if (requestUuid != null) {
+        return {
+            kind: 'request',
+            requestUuid,
+            start,
+            end: start + text.length,
+            text
+        };
+    }
+    if (markdownUuid != null) {
+        return {
+            kind: 'markdown',
+            markdownUuid,
+            start,
+            end: start + text.length,
+            text,
+            selection: parseSelectionSuffix(selectionStartRaw, selectionEndRaw)
+        };
+    }
+    if (terminalIndexRaw != null) {
+        const terminalIndex = Number(terminalIndexRaw);
+        if (!Number.isInteger(terminalIndex) || terminalIndex < 1) {
+            return null;
+        }
+        return {
+            kind: 'terminal',
+            terminalIndex,
+            start,
+            end: start + text.length,
+            text,
+            selection: parseSelectionSuffix(selectionStartRaw, selectionEndRaw, true)
+        };
+    }
+    const selection = parseSelectionSuffix(selectionStartRaw, selectionEndRaw);
+    if (snippetUuid != null) {
+        return {
+            kind: 'snippet',
+            snippetUuid,
+            start,
+            end: start + text.length,
+            text,
+            selection
+        };
+    }
+    if (requestIdRaw == null || phase == null || scriptIndexRaw == null) {
+        return null;
+    }
+    if (phase !== 'pre' && phase !== 'post') {
+        return null;
+    }
+    const scriptIndex = Number(scriptIndexRaw);
+    if (!Number.isInteger(scriptIndex) || scriptIndex < 1) {
+        return null;
+    }
+    const requestId = requestIdRaw === 'active'
+        ? 'active'
+        : Number.isFinite(Number(requestIdRaw))
+            ? Number(requestIdRaw)
+            : null;
+    if (requestId == null) {
+        return null;
+    }
+    return {
+        kind: 'request-script',
+        requestId,
+        phase,
+        scriptIndex,
+        start,
+        end: start + text.length,
+        text,
+        selection
+    };
+}
+/**
+ * Finds syntactically valid `@` script reference candidates in plain text.
+ *
+ * @param text - Composer draft that may contain `@` references.
+ */
+export function findAiScriptReferenceCandidates(text) {
+    const matches = [];
+    const pattern = new RegExp(AI_SCRIPT_REFERENCE_PATTERN.source, 'g');
+    for (const match of text.matchAll(pattern)) {
+        const start = match.index ?? 0;
+        if (!isScriptReferenceBoundary(text, start)) {
+            continue;
+        }
+        const parsed = parseAiScriptReferenceMatch(match, start);
+        if (parsed) {
+            matches.push(parsed);
+        }
+    }
+    return matches;
+}
+/**
+ * Removes valid `@` script reference tokens from plain text.
+ *
+ * @param text - Composer or title prompt text that may contain `@` references.
+ * @returns Text with script references removed and whitespace collapsed.
+ */
+export function stripAiScriptReferences(text) {
+    const candidates = findAiScriptReferenceCandidates(text);
+    if (candidates.length === 0) {
+        return text.replace(/\s+/g, ' ').trim();
+    }
+    let stripped = text;
+    for (const candidate of [...candidates].sort((left, right) => right.start - left.start)) {
+        stripped = stripped.slice(0, candidate.start) + stripped.slice(candidate.end);
+    }
+    return stripped.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Returns whether a parsed `@` reference resolves against the active request tab or snippet library.
+ *
+ * Mirrors `update_request_script` validation in the AI tool executor for request-script kind.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script counts, request id, and snippet library.
+ */
+export function isValidAiScriptReference(reference, context) {
+    if (reference.kind === 'markdown') {
+        if (reference.selection == null) {
+            return false;
+        }
+        return context.markdownSelections?.[reference.text] != null;
+    }
+    if (reference.kind === 'body') {
+        if (reference.selection == null) {
+            return false;
+        }
+        return context.requestBodySelections?.[reference.text] != null;
+    }
+    if (reference.kind === 'terminal') {
+        if (reference.selection == null) {
+            return false;
+        }
+        return context.terminalSelections?.[reference.text] != null;
+    }
+    if (reference.kind === 'snippet') {
+        return (context.snippets ?? []).some((entry) => entry.uuid === reference.snippetUuid);
+    }
+    if (reference.kind === 'collection') {
+        return context.collectionNamesByUuid?.[reference.collectionUuid] != null;
+    }
+    if (reference.kind === 'folder') {
+        return context.folderNamesByUuid?.[reference.folderUuid] != null;
+    }
+    if (reference.kind === 'request') {
+        return context.requestNamesByUuid?.[reference.requestUuid] != null;
+    }
+    if (!context.hasActiveRequestTab) {
+        return false;
+    }
+    if (reference.requestId !== 'active' && reference.requestId !== context.activeRequestId) {
+        return false;
+    }
+    const scriptCount = reference.phase === 'pre' ? context.preScriptCount : context.postScriptCount;
+    return reference.scriptIndex >= 1 && reference.scriptIndex <= scriptCount;
+}
+/**
+ * Returns the display name for a script row, matching the request editor list labels.
+ *
+ * @param script - Script reference entry from the active draft.
+ * @param snippets - Snippet library lookup source.
+ */
+function scriptReferenceDisplayName(script, snippets) {
+    if (script.name?.trim()) {
+        return script.name.trim();
+    }
+    if (script.kind === 'snippet') {
+        const snippet = snippets.find((entry) => entry.uuid === script.snippetUuid);
+        return snippet ? snippet.name : 'Missing snippet';
+    }
+    return 'Inline script';
+}
+/**
+ * Resolves the display name for a valid `@` script reference.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Script or snippet name when resolvable, otherwise null.
+ */
+export function resolveAiScriptReferenceName(reference, context) {
+    if (!isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    if (reference.kind === 'terminal') {
+        return context.terminalSelections?.[reference.text]?.terminalLabel ?? null;
+    }
+    if (reference.kind === 'markdown') {
+        return context.markdownSelections?.[reference.text]?.label ?? null;
+    }
+    if (reference.kind === 'body') {
+        return context.requestBodySelections?.[reference.text]?.label ?? null;
+    }
+    if (reference.kind === 'snippet') {
+        const snippet = (context.snippets ?? []).find((entry) => entry.uuid === reference.snippetUuid);
+        return snippet?.name ?? null;
+    }
+    if (reference.kind === 'collection') {
+        const name = context.collectionNamesByUuid?.[reference.collectionUuid];
+        return name != null ? `Collection: ${name}` : null;
+    }
+    if (reference.kind === 'folder') {
+        const name = context.folderNamesByUuid?.[reference.folderUuid];
+        return name != null ? `Folder: ${name}` : null;
+    }
+    if (reference.kind === 'request') {
+        const name = context.requestNamesByUuid?.[reference.requestUuid];
+        return name != null ? `Request: ${name}` : null;
+    }
+    const scripts = reference.phase === 'pre' ? context.preScripts : context.postScripts;
+    if (scripts == null) {
+        return null;
+    }
+    const script = scripts[reference.scriptIndex - 1];
+    if (script == null) {
+        return null;
+    }
+    return scriptReferenceDisplayName(script, context.snippets ?? []);
+}
+/**
+ * Resolves the JavaScript source for a script row on the active request tab.
+ *
+ * @param script - Script reference entry from the active draft.
+ * @param snippets - Snippet library lookup source.
+ * @returns Script source text, or null when unavailable.
+ */
+function resolveScriptSourceCode(script, snippets) {
+    if (script.kind === 'inline') {
+        return script.code ?? '';
+    }
+    if (script.kind === 'snippet') {
+        const linkedSnippet = snippets.find((entry) => entry.uuid === script.snippetUuid);
+        return linkedSnippet?.code ?? null;
+    }
+    return null;
+}
+/**
+ * Resolves the JavaScript source for a parsed `@` reference.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Script or snippet source text, or null when unavailable.
+ */
+function resolveReferenceSourceCode(reference, context) {
+    if (reference.kind === 'terminal' ||
+        reference.kind === 'markdown' ||
+        reference.kind === 'body' ||
+        reference.kind === 'collection' ||
+        reference.kind === 'folder' ||
+        reference.kind === 'request') {
+        return null;
+    }
+    if (reference.kind === 'snippet') {
+        const snippet = (context.snippets ?? []).find((entry) => entry.uuid === reference.snippetUuid);
+        return snippet?.code ?? null;
+    }
+    const scripts = reference.phase === 'pre' ? context.preScripts : context.postScripts;
+    const script = scripts?.[reference.scriptIndex - 1];
+    if (script == null) {
+        return null;
+    }
+    return resolveScriptSourceCode(script, context.snippets ?? []);
+}
+/**
+ * Returns the 1-based line number for a character offset in script source.
+ *
+ * @param source - Script source text.
+ * @param offset - Character offset into the source.
+ */
+function lineNumberAtOffset(source, offset) {
+    const clamped = Math.min(Math.max(0, offset), source.length);
+    let line = 1;
+    for (let index = 0; index < clamped; index += 1) {
+        if (source[index] === '\n') {
+            line += 1;
+        }
+    }
+    return line;
+}
+/**
+ * Formats a selection range as a human-readable line span for badge labels.
+ *
+ * @param source - Script source text.
+ * @param selection - Character offsets into the script source.
+ * @returns Line span label such as `(line 3)` or `(lines 3-5)`.
+ */
+function formatScriptSelectionLineRange(source, selection) {
+    const clampedStart = Math.min(Math.max(0, selection.start), source.length);
+    const clampedEnd = Math.min(Math.max(clampedStart, selection.end), source.length);
+    const startLine = lineNumberAtOffset(source, clampedStart);
+    const endLine = lineNumberAtOffset(source, Math.max(clampedStart, clampedEnd - 1));
+    if (startLine === endLine) {
+        return `(line ${startLine})`;
+    }
+    return `(lines ${startLine}-${endLine})`;
+}
+/**
+ * Resolves the badge label for a valid `@` script reference, including selection line ranges.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Script name with optional line range, or null when not resolvable.
+ */
+/**
+ * Formats a terminal line span for badge labels.
+ *
+ * @param startLine - 1-based start line of the selection.
+ * @param endLine - 1-based end line of the selection.
+ */
+function formatTerminalSelectionLineRange(startLine, endLine) {
+    if (startLine === endLine) {
+        return `(line ${startLine})`;
+    }
+    return `(lines ${startLine}-${endLine})`;
+}
+export function resolveAiScriptReferenceLabel(reference, context) {
+    const name = resolveAiScriptReferenceName(reference, context);
+    if (name == null) {
+        return null;
+    }
+    if (reference.kind === 'terminal') {
+        const snapshot = context.terminalSelections?.[reference.text];
+        if (snapshot == null) {
+            return name;
+        }
+        return `${name} ${formatTerminalSelectionLineRange(snapshot.startLine, snapshot.endLine)}`;
+    }
+    if (reference.kind === 'markdown') {
+        const snapshot = context.markdownSelections?.[reference.text];
+        if (snapshot == null) {
+            return name;
+        }
+        return `${name} ${formatTerminalSelectionLineRange(snapshot.startLine, snapshot.endLine)}`;
+    }
+    if (reference.kind === 'body') {
+        const snapshot = context.requestBodySelections?.[reference.text];
+        if (snapshot == null) {
+            return name;
+        }
+        return `${name} ${formatTerminalSelectionLineRange(snapshot.startLine, snapshot.endLine)}`;
+    }
+    if (reference.selection == null) {
+        return name;
+    }
+    const source = resolveReferenceSourceCode(reference, context);
+    if (source == null) {
+        return name;
+    }
+    return `${name} ${formatScriptSelectionLineRange(source, reference.selection)}`;
+}
+/**
+ * Clamps selection offsets to script source bounds and returns the selected substring.
+ *
+ * @param source - Full script source text.
+ * @param selection - Character offsets from the `@` reference suffix.
+ */
+function clampScriptSelection(source, selection) {
+    const start = Math.min(Math.max(0, selection.start), source.length);
+    const end = Math.min(Math.max(start, selection.end), source.length);
+    return {
+        start,
+        end,
+        text: source.slice(start, end)
+    };
+}
+/**
+ * Formats the line span label for agent context without surrounding parentheses.
+ *
+ * @param source - Script source text.
+ * @param selection - Clamped character offsets into the script source.
+ */
+function formatScriptSelectionLineSpan(source, selection) {
+    return formatScriptSelectionLineRange(source, selection).replace(/^\(|\)$/g, '');
+}
+/**
+ * Formats one resolved terminal selection reference for the agent context block.
+ *
+ * @param reference - Parsed `@term` reference with a line-range suffix.
+ * @param context - Terminal selection snapshots keyed by reference token.
+ * @returns Context block for one terminal reference, or null when not resolvable.
+ */
+function formatTerminalSelectionContextBlock(reference, context) {
+    if (reference.selection == null || !isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    const snapshot = context.terminalSelections?.[reference.text];
+    if (snapshot == null) {
+        return null;
+    }
+    const lineSpan = snapshot.startLine === snapshot.endLine
+        ? `line ${snapshot.startLine}`
+        : `lines ${snapshot.startLine}-${snapshot.endLine}`;
+    return [
+        `Reference ${reference.text} — footer terminal "${snapshot.terminalLabel}" (terminal ${reference.terminalIndex} in the tab list).`,
+        `Selected terminal output (${lineSpan}):`,
+        '```text',
+        snapshot.selectedText,
+        '```',
+        'Surrounding terminal context (includes lines before and after the selection):',
+        '```text',
+        snapshot.contextText,
+        '```'
+    ].join('\n');
+}
+/**
+ * Formats one resolved markdown selection reference for the agent context block.
+ *
+ * @param reference - Parsed `@markdown` reference with a character-range suffix.
+ * @param context - Markdown selection snapshots keyed by reference token.
+ * @returns Context block for one markdown reference, or null when not resolvable.
+ */
+function formatMarkdownSelectionContextBlock(reference, context) {
+    if (reference.selection == null || !isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    const snapshot = context.markdownSelections?.[reference.text];
+    if (snapshot == null) {
+        return null;
+    }
+    const lineSpan = snapshot.startLine === snapshot.endLine
+        ? `line ${snapshot.startLine}`
+        : `lines ${snapshot.startLine}-${snapshot.endLine}`;
+    return [
+        `Reference ${reference.text} — markdown "${snapshot.label}".`,
+        `Selected markdown text (characters ${snapshot.startOffset}–${snapshot.endOffset}, ${lineSpan}):`,
+        '```markdown',
+        snapshot.selectedText,
+        '```',
+        'Call get_markdown_document with the same uuid when you need the full document or comment source.'
+    ].join('\n');
+}
+/**
+ * Formats one resolved raw-body selection reference for the agent context block.
+ *
+ * @param reference - Parsed `@body` reference with a character-range suffix.
+ * @param context - Raw-body selection snapshots keyed by reference token.
+ * @returns Context block for one body reference, or null when not resolvable.
+ */
+function formatRequestBodySelectionContextBlock(reference, context) {
+    if (reference.selection == null || !isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    const snapshot = context.requestBodySelections?.[reference.text];
+    if (snapshot == null) {
+        return null;
+    }
+    const lineSpan = snapshot.startLine === snapshot.endLine
+        ? `line ${snapshot.startLine}`
+        : `lines ${snapshot.startLine}-${snapshot.endLine}`;
+    return [
+        `Reference ${reference.text} — raw request body "${snapshot.label}".`,
+        `Selected raw body text (characters ${snapshot.startOffset}–${snapshot.endOffset}, ${lineSpan}):`,
+        '```text',
+        snapshot.selectedText,
+        '```',
+        'Call get_active_request_details when you need the full body (including body_raw / body_raw_effective). Use update_active_request with body_raw to replace the raw body text.'
+    ].join('\n');
+}
+function formatScriptSelectionContextBlock(reference, context) {
+    if (reference.kind === 'terminal') {
+        return formatTerminalSelectionContextBlock(reference, context);
+    }
+    if (reference.kind === 'markdown') {
+        return formatMarkdownSelectionContextBlock(reference, context);
+    }
+    if (reference.kind === 'body') {
+        return formatRequestBodySelectionContextBlock(reference, context);
+    }
+    if (reference.selection == null || !isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    const source = resolveReferenceSourceCode(reference, context);
+    if (source == null) {
+        return null;
+    }
+    const name = resolveAiScriptReferenceName(reference, context) ?? 'Unnamed script';
+    const clampedSelection = clampScriptSelection(source, reference.selection);
+    const lineSpan = formatScriptSelectionLineSpan(source, clampedSelection);
+    if (reference.kind === 'snippet') {
+        return [
+            `Reference ${reference.text} — standalone library snippet "${name}" (not linked to any specific request).`,
+            'Full snippet source:',
+            '```js',
+            source,
+            '```',
+            `Selected text (characters ${clampedSelection.start}–${clampedSelection.end}, ${lineSpan}):`,
+            '```js',
+            clampedSelection.text,
+            '```'
+        ].join('\n');
+    }
+    if (reference.kind !== 'request-script') {
+        return null;
+    }
+    const phaseLabel = reference.phase === 'pre' ? 'pre-request' : 'post-request';
+    const requestLabel = reference.requestId === 'active'
+        ? 'of the active request'
+        : `of request id ${reference.requestId}`;
+    return [
+        `Reference ${reference.text} — script "${name}" (${phaseLabel} script ${reference.scriptIndex} ${requestLabel}).`,
+        'Full script source:',
+        '```js',
+        source,
+        '```',
+        `Selected text (characters ${clampedSelection.start}–${clampedSelection.end}, ${lineSpan}):`,
+        '```js',
+        clampedSelection.text,
+        '```'
+    ].join('\n');
+}
+/**
+ * Formats one valid whole-script `@` reference (no `#selection` suffix) for agent context.
+ *
+ * @param reference - Parsed `@` script reference without a selection range.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Context block with full script source, or null when not resolvable.
+ */
+function formatWholeScriptReferenceContextBlock(reference, context) {
+    if (reference.selection != null ||
+        reference.kind === 'terminal' ||
+        reference.kind === 'markdown' ||
+        reference.kind === 'body' ||
+        reference.kind === 'collection' ||
+        reference.kind === 'folder' ||
+        reference.kind === 'request') {
+        return null;
+    }
+    if (!isValidAiScriptReference(reference, context)) {
+        return null;
+    }
+    const source = resolveReferenceSourceCode(reference, context);
+    if (source == null) {
+        return null;
+    }
+    const name = resolveAiScriptReferenceName(reference, context) ?? 'Unnamed script';
+    if (reference.kind === 'snippet') {
+        return [
+            `Reference ${reference.text} — standalone library snippet "${name}" (not linked to any specific request).`,
+            'Full snippet source:',
+            '```js',
+            source,
+            '```'
+        ].join('\n');
+    }
+    if (reference.kind !== 'request-script') {
+        return null;
+    }
+    const phaseLabel = reference.phase === 'pre' ? 'pre-request' : 'post-request';
+    const requestLabel = reference.requestId === 'active'
+        ? 'of the active request'
+        : `of request id ${reference.requestId}`;
+    return [
+        `Reference ${reference.text} — script "${name}" (${phaseLabel} script ${reference.scriptIndex} ${requestLabel}).`,
+        'Full script source:',
+        '```js',
+        source,
+        '```'
+    ].join('\n');
+}
+/**
+ * Formats agent context for one `@` script reference, with or without a selection suffix.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script rows and snippet library.
+ */
+function formatScriptReferenceContextBlock(reference, context) {
+    if (reference.selection != null) {
+        return formatScriptSelectionContextBlock(reference, context);
+    }
+    return formatWholeScriptReferenceContextBlock(reference, context);
+}
+/**
+ * Builds an ephemeral system message that expands valid `@` script references in the user message.
+ *
+ * References with a `#start.end` suffix include the selected substring; whole-script references
+ * include the full source so the model can answer questions without relying on tool calls alone.
+ *
+ * The returned text is injected into the LLM step messages only; it is not persisted in chat
+ * history so the composer can keep rendering compact badges.
+ *
+ * @param text - User message that may contain `@` script references.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Formatted context block, or null when no valid references are present.
+ */
+export function buildAiScriptSelectionContextMessage(text, context) {
+    const candidates = findAiScriptReferenceCandidates(text);
+    const resolved = candidates
+        .map((reference) => ({
+        reference,
+        block: formatScriptReferenceContextBlock(reference, context)
+    }))
+        .filter((entry) => entry.block != null ? true : false);
+    if (resolved.length === 0) {
+        return null;
+    }
+    const blocks = resolved.map((entry) => entry.block);
+    const hasTerminalSelection = resolved.some((entry) => entry.reference.kind === 'terminal' && entry.reference.selection != null);
+    const hasMarkdownSelection = resolved.some((entry) => entry.reference.kind === 'markdown' && entry.reference.selection != null);
+    const hasBodySelection = resolved.some((entry) => entry.reference.kind === 'body' && entry.reference.selection != null);
+    const hasScriptSelection = resolved.some((entry) => (entry.reference.kind === 'request-script' || entry.reference.kind === 'snippet') &&
+        entry.reference.selection != null);
+    const hasWholeScriptReference = resolved.some((entry) => (entry.reference.kind === 'request-script' || entry.reference.kind === 'snippet') &&
+        entry.reference.selection == null);
+    const headerParts = [];
+    if (hasTerminalSelection) {
+        headerParts.push('The user selected terminal output and is asking specifically about the SELECTED TEXT below.');
+    }
+    if (hasMarkdownSelection) {
+        headerParts.push('The user selected markdown text and is asking specifically about the SELECTED TEXT below.');
+    }
+    if (hasBodySelection) {
+        headerParts.push('The user selected raw request body text and is asking specifically about the SELECTED TEXT below.');
+    }
+    if (hasScriptSelection) {
+        headerParts.push('The user selected part of a script and is asking specifically about the SELECTED TEXT below.');
+    }
+    if (hasWholeScriptReference) {
+        headerParts.push('The user referenced one or more scripts via @ mentions. Use the script sources below to answer their question.');
+    }
+    const footerParts = [];
+    if (hasScriptSelection) {
+        footerParts.push('Focus your answer on the selected region.');
+    }
+    else if (hasBodySelection) {
+        footerParts.push('Focus your answer on the selected raw body region. Call get_active_request_details when you need the full body, and use update_active_request with body_raw to edit it.');
+    }
+    else if (hasMarkdownSelection) {
+        footerParts.push('Focus your answer on the selected markdown region. Call get_markdown_document when you need the full document or comment source.');
+    }
+    else if (hasWholeScriptReference) {
+        footerParts.push('Answer using the referenced script source below.');
+    }
+    if (hasTerminalSelection) {
+        footerParts.push('Terminal output references cannot be edited via tools. Explain, diagnose, or suggest shell commands the user can run.');
+    }
+    if (hasMarkdownSelection) {
+        footerParts.push('Markdown documents and request comments referenced with @markdown.<uuid> cannot be edited via tools. Propose replacement markdown in your reply for the user to paste back into the editor.');
+    }
+    if (hasBodySelection) {
+        footerParts.push('Raw body selections referenced with @body#start.end can be edited via update_active_request with body_raw (verbatim wire text for multipart/urlencoded). Prefer body_raw over structured body when the user is editing the Raw body drawer.');
+    }
+    if (resolved.some((entry) => entry.reference.kind === 'request-script')) {
+        footerParts.push(hasScriptSelection
+            ? 'When editing request scripts, use update_request_script with the same phase and scriptIndex from the reference, and respect the #start.end character offsets from the @ tag.'
+            : 'When editing request scripts, use update_request_script with the same phase and scriptIndex from the @ reference.');
+    }
+    if (resolved.some((entry) => entry.reference.kind === 'snippet')) {
+        footerParts.push('Standalone library snippets referenced with @snippet.<uuid> cannot be edited via tools. Propose replacement code in your reply for the user to paste back into the snippet editor.');
+    }
+    return [headerParts.join(' '), '', ...blocks, '', footerParts.join(' ')].join('\n');
+}
+/**
+ * Splits composer text into plain and highlightable `@` script reference segments.
+ *
+ * @param text - Composer draft.
+ * @param context - Active tab state for semantic validation.
+ */
+export function tokenizeChatComposerText(text, context) {
+    const candidates = findAiScriptReferenceCandidates(text);
+    const tokens = [];
+    let lastIndex = 0;
+    for (const candidate of candidates) {
+        if (candidate.start < lastIndex) {
+            continue;
+        }
+        const highlight = isValidAiScriptReference(candidate, context);
+        if (candidate.start > lastIndex) {
+            tokens.push({ text: text.slice(lastIndex, candidate.start), highlight: false });
+        }
+        tokens.push({
+            text: candidate.text,
+            highlight,
+            reference: highlight ? candidate : undefined
+        });
+        lastIndex = candidate.end;
+    }
+    if (lastIndex < text.length) {
+        tokens.push({ text: text.slice(lastIndex), highlight: false });
+    }
+    return tokens;
+}
+//# sourceMappingURL=scriptReferences.js.map