neoctl 0.2.0 → 0.2.1

package/dist/context/prompts.js

@@ -1,7 +1,7 @@
 export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__";
 export function buildDefaultSystemPromptSections(enabledTools = []) {
     const hasImageGenerationTool = enabledTools.includes("image2");
-    const hasVisionTool = enabledTools.includes("vision");
+    const hasLoadImageTool = enabledTools.includes("load_image");
     return [
         {
             name: "Agent Scaffold",
@@ -30,9 +30,9 @@ export function buildDefaultSystemPromptSections(enabledTools = []) {
                     ? `Available tools are provided separately. Stable tool prefix: ${enabledTools.join(", ")}.`
                     : "Available tools are provided separately by the runtime.",
                 "When using tools, you may briefly state the intent of the tool call; if a tool result contains valuable information, you may briefly report it.",
-                hasVisionTool
-                    ? "When the user asks you to inspect, describe, OCR, or answer questions about a prior/current image, use the vision tool with imageRefs such as [img#1]; it can resolve stored historical image paths and send the actual image to a vision-capable model."
-                    : "This runtime has no vision inspection tool. Do not pretend to visually inspect stored image paths; ask the user to switch to a vision-capable model/runtime if visual analysis is required.",
+                hasLoadImageTool
+                    ? "When you need to inspect, describe, OCR, or answer questions about any image (including historical images from earlier in the conversation that may have been compacted), use the load_image tool with image ids (e.g. img_1) or labels. This loads the actual image pixels directly into your context so you can see them with your own multimodal capabilities. The image registry in compact boundary messages lists all available historical images."
+                    : "This runtime has no image loading tool. Do not pretend to visually inspect stored image paths; ask the user to switch to a vision-capable model/runtime if visual analysis is required.",
                 hasImageGenerationTool
                     ? "When the user asks for drawing/image generation or image editing/modification, use the image2 tool. It is backed by OpenAI's Images API, defaults to OpenAI model gpt-image-2, and supports mode=generate for new images and mode=edit for modifying existing images. If image2 validation fails, tell the user the model and exact parameter reason from the tool result."
                     : "This runtime has no drawing/image generation/editing tool. If the user asks you to draw, create, render, generate, or edit an image, say that the current model/provider does not have drawing capability instead of pretending to generate one.",

package/dist/context/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/context/prompts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/context/prompts.ts"],"names":[],"mappings":"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"}

package/dist/core/commands.d.ts

@@ -0,0 +1,66 @@
+export type ModelReasoningArgument = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "default" | "off";
+export type RuntimeCommand = {
+    type: "help";
+} | {
+    type: "cost";
+} | {
+    type: "compact";
+} | {
+    type: "pure";
+} | {
+    type: "env";
+} | {
+    type: "exit";
+} | {
+    type: "export";
+    path: string;
+} | {
+    type: "login";
+} | {
+    type: "log";
+    path?: string;
+    off?: boolean;
+} | {
+    type: "model";
+    model?: string;
+    reasoning?: ModelReasoningArgument;
+} | {
+    type: "new";
+} | {
+    type: "reset";
+} | {
+    type: "sessions";
+} | {
+    type: "state";
+} | {
+    type: "input";
+    text: string;
+};
+export type RuntimeCommandArgumentSpec = "none" | "required" | "optional" | "log";
+export interface RuntimeCommandDefinition {
+    name: string;
+    usage: string;
+    description: string;
+    arguments: RuntimeCommandArgumentSpec;
+    aliases?: string[];
+}
+export declare const runtimeCommandDefinitions: RuntimeCommandDefinition[];
+export declare const commandUsages: string[];
+export declare function parseRuntimeCommand(line: string): RuntimeCommand;
+export declare function isValidRuntimeCommandLine(line: string): boolean;
+export declare function isModelReasoningArgument(value: string): value is ModelReasoningArgument;
+export declare const runtimeHelpText: string;
+export interface CliRuntimeCommandParseResult {
+    line: string;
+    definition: RuntimeCommandDefinition;
+}
+export declare function parseCliRuntimeCommandArgs(argv: string[]): CliRuntimeCommandParseResult | undefined;
+export declare function cliHelpText(binaryName?: string): string;
+export type ReplCommand = RuntimeCommand;
+export type ReplCommandArgumentSpec = RuntimeCommandArgumentSpec;
+export type ReplCommandDefinition = RuntimeCommandDefinition;
+export declare const replCommandDefinitions: RuntimeCommandDefinition[];
+export declare const helpText: string;
+export declare const parseReplCommand: typeof parseRuntimeCommand;
+export declare const isValidReplCommandLine: typeof isValidRuntimeCommandLine;
+export declare const parseCliReplCommandArgs: typeof parseCliRuntimeCommandArgs;

package/dist/core/commands.js

@@ -0,0 +1,151 @@
+export const runtimeCommandDefinitions = [
+    { name: "/help", usage: "/help", description: "Show commands", arguments: "none" },
+    { name: "/cost", usage: "/cost", description: "Show total token usage for this session", arguments: "none" },
+    { name: "/compact", usage: "/compact", description: "Manually compact earlier context", arguments: "none" },
+    { name: "/pure", usage: "/pure", description: "Sanitize context after WAF/risk blocks without resetting", arguments: "none" },
+    { name: "/export", usage: "/export <absolute-md-path>", description: "Export the current session transcript as detailed Markdown", arguments: "required" },
+    { name: "/env", usage: "/env", description: "Open the neoctl configuration directory", arguments: "none" },
+    { name: "/login", usage: "/login", description: "Configure and save a model provider to the env file", arguments: "none" },
+    { name: "/model", usage: "/model [model-id] [effort|default|off]", description: "Show or switch model and supported reasoning effort", arguments: "optional" },
+    { name: "/new", usage: "/new", description: "Start a new session; running current session continues in background", arguments: "none" },
+    { name: "/log", usage: "/log <dir>", description: "Write model communication logs to an absolute directory", arguments: "required" },
+    { name: "/log off", usage: "/log off", description: "Disable model communication logs", arguments: "none" },
+    { name: "/sessions", usage: "/sessions", description: "Browse saved sessions", arguments: "none" },
+    { name: "/state", usage: "/state", description: "Show query engine state", arguments: "none" },
+    { name: "/reset", usage: "/reset", description: "Clear current transcript and add a reset marker", arguments: "none" },
+    { name: "/exit", usage: "/exit", description: "Quit", arguments: "none", aliases: ["/quit"] },
+];
+export const commandUsages = runtimeCommandDefinitions.map((command) => command.usage);
+export function parseRuntimeCommand(line) {
+    const parsed = parseSlashCommandLine(line);
+    if (!parsed.valid)
+        return { type: "input", text: line };
+    const { name, argument } = parsed;
+    if (name === "/help")
+        return { type: "help" };
+    if (name === "/cost")
+        return { type: "cost" };
+    if (name === "/compact")
+        return { type: "compact" };
+    if (name === "/pure")
+        return { type: "pure" };
+    if (name === "/export")
+        return { type: "export", path: argument };
+    if (name === "/env")
+        return { type: "env" };
+    if (name === "/login")
+        return { type: "login" };
+    if (name === "/exit" || name === "/quit")
+        return { type: "exit" };
+    if (name === "/model")
+        return parseModelCommand(argument) ?? { type: "input", text: line };
+    if (name === "/new")
+        return { type: "new" };
+    if (name === "/log") {
+        if (argument.toLowerCase() === "off")
+            return { type: "log", off: true };
+        return { type: "log", path: argument };
+    }
+    if (name === "/reset")
+        return { type: "reset" };
+    if (name === "/sessions")
+        return { type: "sessions" };
+    if (name === "/state")
+        return { type: "state" };
+    return { type: "input", text: line };
+}
+export function isValidRuntimeCommandLine(line) {
+    return parseSlashCommandLine(line).valid && parseRuntimeCommand(line).type !== "input";
+}
+export function isModelReasoningArgument(value) {
+    return value === "none" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max" || value === "default" || value === "off";
+}
+function parseModelCommand(argument) {
+    const tokens = argument.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return { type: "model" };
+    if (tokens.length > 2)
+        return undefined;
+    if (tokens.length === 1) {
+        const [single] = tokens;
+        return isModelReasoningArgument(single)
+            ? { type: "model", reasoning: single }
+            : { type: "model", model: single };
+    }
+    const [model, reasoning] = tokens;
+    if (!isModelReasoningArgument(reasoning))
+        return undefined;
+    return { type: "model", model, reasoning };
+}
+function parseSlashCommandLine(line) {
+    if (!line.startsWith("/"))
+        return { valid: false };
+    const trimmed = line.trimEnd();
+    const match = /^(\/\S+)(?:\s+(.*))?$/.exec(trimmed);
+    if (!match)
+        return { valid: false };
+    const typedName = match[1].toLowerCase();
+    const argument = match[2]?.trim() ?? "";
+    const definition = runtimeCommandDefinitions.find((command) => command.name.toLowerCase() === typedName || command.aliases?.some((alias) => alias.toLowerCase() === typedName));
+    if (!definition)
+        return { valid: false };
+    if (definition.arguments === "none" && argument.length > 0)
+        return { valid: false };
+    if (definition.arguments === "required" && argument.length === 0)
+        return { valid: false };
+    if (definition.arguments === "log" && argument.length === 0)
+        return { valid: false };
+    return { valid: true, name: typedName, argument };
+}
+const helpUsageWidth = Math.max(...runtimeCommandDefinitions.map((command) => command.usage.length));
+export const runtimeHelpText = [
+    "Commands:",
+    ...runtimeCommandDefinitions.map((command) => `  ${command.usage.padEnd(helpUsageWidth)}  ${command.description}`),
+].join("\n");
+export function parseCliRuntimeCommandArgs(argv) {
+    if (argv.length === 0)
+        return undefined;
+    const first = argv[0];
+    const match = /^--?([^=\s]+)(?:=(.*))?$/.exec(first);
+    if (!match)
+        return undefined;
+    const commandName = `/${match[1].toLowerCase()}`;
+    const definition = runtimeCommandDefinitions.find((command) => command.name.toLowerCase() === commandName || command.aliases?.some((alias) => alias.toLowerCase() === commandName));
+    if (!definition)
+        return undefined;
+    const inlineArgument = match[2];
+    const rest = inlineArgument === undefined ? argv.slice(1) : [inlineArgument, ...argv.slice(1)];
+    if (definition.arguments === "none" && rest.length > 0)
+        return undefined;
+    if ((definition.arguments === "required" || definition.arguments === "log") && rest.length === 0)
+        return undefined;
+    const line = rest.length === 0 ? definition.name : `${definition.name} ${rest.join(" ")}`;
+    return { line, definition };
+}
+export function cliHelpText(binaryName = "neo") {
+    const cliCommandUsages = runtimeCommandDefinitions.map((command) => command.usage.replace(/^\//, "-"));
+    const cliUsageWidth = Math.max(...cliCommandUsages.map((usage) => usage.length));
+    return [
+        `Usage: ${binaryName} [command]`,
+        "",
+        "CLI commands mirror slash commands; use '-' or '--' in place of '/'.",
+        "",
+        "Commands:",
+        ...runtimeCommandDefinitions.map((command) => {
+            const usage = command.usage.replace(/^\//, "-");
+            return `  ${usage.padEnd(cliUsageWidth)}  ${command.description}`;
+        }),
+        "",
+        "Examples:",
+        `  ${binaryName} -help`,
+        `  ${binaryName} -model`,
+        `  ${binaryName} -model gpt-5.5 high`,
+        `  ${binaryName} -new`,
+    ].join("\n");
+}
+export const replCommandDefinitions = runtimeCommandDefinitions;
+export const helpText = runtimeHelpText;
+export const parseReplCommand = parseRuntimeCommand;
+export const isValidReplCommandLine = isValidRuntimeCommandLine;
+export const parseCliReplCommandArgs = parseCliRuntimeCommandArgs;
+//# sourceMappingURL=commands.js.map

package/dist/core/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/core/commands.ts"],"names":[],"mappings":"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"}

package/dist/core/context-metrics.d.ts

@@ -1,10 +1,13 @@
 import type { ToolDefinition } from "../tools/tool.js";
 import type { ContextMetrics } from "../types/events.js";
 import type { Message } from "../types/messages.js";
-export declare function buildContextMetrics(input: {
+export interface BuildContextMetricsInput {
     model?: string;
     messages: readonly Message[];
     systemPrompt: string;
     tools: readonly ToolDefinition[];
-}): ContextMetrics;
+    cachedToolsAndPromptTokens?: number;
+}
+export declare function buildContextMetrics(input: BuildContextMetricsInput): ContextMetrics;
 export declare function estimateTextTokens(text: string): number;
+export declare function computeStaticTokens(systemPrompt: string, tools: readonly ToolDefinition[]): number;

package/dist/core/context-metrics.js

@@ -1,12 +1,61 @@
 import { resolveContextWindowTokens } from "../model/context-window.js";
+let _encode;
+let _encoderLoadFailed = false;
+function getEncoder() {
+    if (_encode || _encoderLoadFailed)
+        return _encode;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require("gpt-tokenizer");
+        _encode = mod.encode ?? mod.default?.encode;
+        if (!_encode)
+            _encoderLoadFailed = true;
+    }
+    catch {
+        _encoderLoadFailed = true;
+    }
+    return _encode;
+}
+const TOKEN_CACHE_MAX = 128;
+const _tokenCache = new Map();
+function cachedTokenCount(text) {
+    if (!text)
+        return 0;
+    const cacheKey = text.length <= 4096 ? text : undefined;
+    if (cacheKey) {
+        const cached = _tokenCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+    }
+    const encode = getEncoder();
+    const count = encode ? encode(text).length : heuristicTokenCount(text);
+    if (cacheKey) {
+        if (_tokenCache.size >= TOKEN_CACHE_MAX) {
+            const first = _tokenCache.keys().next().value;
+            if (first !== undefined)
+                _tokenCache.delete(first);
+        }
+        _tokenCache.set(cacheKey, count);
+    }
+    return count;
+}
 export function buildContextMetrics(input) {
-    const serialized = [
-        input.systemPrompt,
-        ...input.messages.map(serializeMessageForMetrics),
-        JSON.stringify(input.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.inputSchema }))),
-    ].join("\n");
-    const estimatedChars = serialized.length;
-    const estimatedInputTokens = estimateTextTokens(serialized);
+    let estimatedInputTokens;
+    let estimatedChars;
+    if (input.cachedToolsAndPromptTokens !== undefined) {
+        const messageSerialized = input.messages.map(serializeMessageForMetrics).join("\n");
+        estimatedChars = input.systemPrompt.length + messageSerialized.length;
+        estimatedInputTokens = input.cachedToolsAndPromptTokens + estimateTextTokens(messageSerialized);
+    }
+    else {
+        const serialized = [
+            input.systemPrompt,
+            ...input.messages.map(serializeMessageForMetrics),
+            JSON.stringify(input.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.inputSchema }))),
+        ].join("\n");
+        estimatedChars = serialized.length;
+        estimatedInputTokens = estimateTextTokens(serialized);
+    }
     const window = resolveContextWindowTokens(input.model);
     return {
         model: input.model,
@@ -31,6 +80,21 @@ export function buildContextMetrics(input) {
     };
 }
 export function estimateTextTokens(text) {
+    if (!text)
+        return 0;
+    if (text.length <= 8192)
+        return cachedTokenCount(text);
+    let total = 0;
+    for (let i = 0; i < text.length; i += 8192) {
+        total += cachedTokenCount(text.slice(i, i + 8192));
+    }
+    return total;
+}
+export function computeStaticTokens(systemPrompt, tools) {
+    const toolsSerialized = JSON.stringify(tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.inputSchema })));
+    return estimateTextTokens(systemPrompt) + estimateTextTokens(toolsSerialized);
+}
+function heuristicTokenCount(text) {
     if (!text)
         return 0;
     let tokens = 0;
@@ -63,11 +127,23 @@ export function estimateTextTokens(text) {
 function serializeMessageForMetrics(message) {
     return `${message.role}: ${message.blocks.map(serializeBlockForMetrics).join("\n")}`;
 }
+/**
+ * Most vision APIs charge ~85 tokens per tile (typically 512x512).
+ * A typical base64 image of ~200KB decodes to roughly 150K pixels ≈ ~1 tile ≈ 85 tokens.
+ * Larger images get more tiles. We estimate based on base64 length as a proxy for pixel count.
+ */
+function estimateImageTokens(base64Length) {
+    const estimatedBytes = Math.floor(base64Length * 0.75);
+    const tiles = Math.max(1, Math.ceil(estimatedBytes / 200_000));
+    return tiles * 85;
+}
 function serializeBlockForMetrics(block) {
     if (block.type === "text")
         return block.text;
-    if (block.type === "image")
-        return `[image ${block.mimeType} ${block.data.length} base64 chars]`;
+    if (block.type === "image") {
+        const imageTokens = estimateImageTokens(block.data.length);
+        return `${"x".repeat(imageTokens * 4)}`;
+    }
     if (block.type === "thinking")
         return block.text;
     if (block.type === "tool_use")

package/dist/core/context-metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-metrics.js","sourceRoot":"","sources":["../../src/core/context-metrics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context-metrics.js","sourceRoot":"","sources":["../../src/core/context-metrics.ts"],"names":[],"mappings":"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"}

package/dist/core/image-registry.d.ts

@@ -0,0 +1,42 @@
+import type { Message } from "../types/messages.js";
+export interface ImageEntry {
+    id: string;
+    label?: string;
+    mimeType: string;
+    storagePath?: string;
+    storageFormat?: "base64" | "data-url";
+    sourceMessageId: string;
+    sourceRole: string;
+    origin: "user" | "generated" | "tool" | "unknown";
+    /** Approximate index within the conversation timeline. */
+    turnIndex: number;
+}
+export interface ImageRegistry {
+    images: ImageEntry[];
+}
+/**
+ * Scan messages and build a registry of all images encountered.
+ * Each image block gets a stable entry with enough info to reload later.
+ */
+export declare function buildImageRegistry(messages: readonly Message[], startingTurnIndex?: number): ImageRegistry;
+/**
+ * Merge a previous registry (from a compact boundary) with newly extracted entries,
+ * deduplicating by storagePath when available.
+ */
+export declare function mergeImageRegistries(previous: ImageRegistry, current: ImageRegistry): ImageRegistry;
+/**
+ * Extract a previously persisted ImageRegistry from a compact boundary message's metadata.
+ */
+export declare function extractRegistryFromBoundary(messages: readonly Message[]): ImageRegistry | undefined;
+/**
+ * Build a human-readable listing of available images for the model to reference.
+ */
+export declare function formatImageRegistryForContext(registry: ImageRegistry): string;
+/**
+ * Load the raw base64 data for an image entry. Returns undefined if unreadable.
+ */
+export declare function loadImageData(entry: ImageEntry): string | undefined;
+/**
+ * Resolve an image reference (id like "img_3", label, or storage path) against a registry.
+ */
+export declare function resolveImageRef(registry: ImageRegistry, ref: string): ImageEntry | undefined;

package/dist/core/image-registry.js

@@ -0,0 +1,128 @@
+import { readFileSync } from "node:fs";
+/**
+ * Scan messages and build a registry of all images encountered.
+ * Each image block gets a stable entry with enough info to reload later.
+ */
+export function buildImageRegistry(messages, startingTurnIndex = 0) {
+    const images = [];
+    let turnIndex = startingTurnIndex;
+    for (const message of messages) {
+        for (const block of message.blocks) {
+            if (block.type !== "image")
+                continue;
+            images.push({
+                id: `img_${images.length + 1}`,
+                label: block.label,
+                mimeType: block.mimeType,
+                storagePath: block.storage?.path,
+                storageFormat: block.storage?.format,
+                sourceMessageId: message.id,
+                sourceRole: message.role,
+                origin: inferImageOrigin(message, block),
+                turnIndex,
+            });
+        }
+        turnIndex += 1;
+    }
+    return { images };
+}
+/**
+ * Merge a previous registry (from a compact boundary) with newly extracted entries,
+ * deduplicating by storagePath when available.
+ */
+export function mergeImageRegistries(previous, current) {
+    const seen = new Set();
+    const merged = [];
+    for (const entry of previous.images) {
+        const key = entry.storagePath ?? `${entry.sourceMessageId}:${entry.label}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(entry);
+    }
+    for (const entry of current.images) {
+        const key = entry.storagePath ?? `${entry.sourceMessageId}:${entry.label}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push({ ...entry, id: `img_${merged.length + 1}` });
+    }
+    return { images: merged };
+}
+/**
+ * Extract a previously persisted ImageRegistry from a compact boundary message's metadata.
+ */
+export function extractRegistryFromBoundary(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const meta = messages[i].metadata;
+        if (meta?.compactBoundary && meta.imageRegistry) {
+            return meta.imageRegistry;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build a human-readable listing of available images for the model to reference.
+ */
+export function formatImageRegistryForContext(registry) {
+    if (registry.images.length === 0)
+        return "";
+    const lines = registry.images.map((entry) => {
+        const label = entry.label ? `"${entry.label}"` : `unlabeled`;
+        const origin = entry.origin !== "unknown" ? ` (${entry.origin})` : "";
+        const path = entry.storagePath ? ` [stored: ${entry.storagePath}]` : " [no storage]";
+        return `- ${entry.id}: ${label}, ${entry.mimeType}${origin}${path}`;
+    });
+    return [
+        "Available images from conversation history (use load_image tool with the id to examine any image):",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Load the raw base64 data for an image entry. Returns undefined if unreadable.
+ */
+export function loadImageData(entry) {
+    if (!entry.storagePath)
+        return undefined;
+    try {
+        return readFileSync(entry.storagePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve an image reference (id like "img_3", label, or storage path) against a registry.
+ */
+export function resolveImageRef(registry, ref) {
+    const normalized = ref.trim().toLowerCase();
+    const byId = registry.images.find((e) => e.id.toLowerCase() === normalized);
+    if (byId)
+        return byId;
+    const numMatch = /^(?:\[?img[_#]?|image\s*)?(\d+)\]?$/i.exec(normalized);
+    if (numMatch) {
+        const idx = Number(numMatch[1]) - 1;
+        if (idx >= 0 && idx < registry.images.length)
+            return registry.images[idx];
+    }
+    const byLabel = registry.images.find((e) => e.label?.toLowerCase() === normalized);
+    if (byLabel)
+        return byLabel;
+    const byPath = registry.images.find((e) => e.storagePath?.toLowerCase() === normalized ||
+        e.storagePath?.toLowerCase().endsWith(normalized));
+    if (byPath)
+        return byPath;
+    return undefined;
+}
+function inferImageOrigin(message, _block) {
+    if (message.role === "user")
+        return "user";
+    if (message.metadata?.generatedImages || message.metadata?.tool === "image2")
+        return "generated";
+    if (message.role === "tool_result")
+        return "tool";
+    if (message.role === "assistant")
+        return "generated";
+    return "unknown";
+}
+//# sourceMappingURL=image-registry.js.map

package/dist/core/image-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-registry.js","sourceRoot":"","sources":["../../src/core/image-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/message-pipeline.d.ts

@@ -1,4 +1,5 @@
 import { type Message } from "../types/messages.js";
+import { type ImageRegistry } from "./image-registry.js";
 export interface ToolResultBudgetOptions {
     maxSerializedLength?: number;
 }
@@ -8,3 +9,8 @@ export declare function ensureToolResultPairing(messages: readonly Message[]): M
 export declare function hasValidToolResultPairing(messages: readonly Message[]): boolean;
 export declare function prependUserContext<T extends object>(messages: readonly Message[], userContext: T): Message[];
 export declare function appendSystemContext<T extends object>(systemPrompt: string, systemContext: T): string;
+/**
+ * Build a complete ImageRegistry from the current message set,
+ * merging any registry persisted in a compact boundary with images from recent messages.
+ */
+export declare function getImageRegistryFromMessages(messages: readonly Message[]): ImageRegistry;