Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(ai): reserve generated image space before loading

Wolf Mermelsteinf196259903b0
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 63497831a6..d42c47f8cc 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -7112,39 +7112,70 @@
"crates/workspace-hack"
],
"image_generation": [
+ "crates/activity",
"crates/agent",
+ "crates/agent_fold",
+ "crates/agent_runtime_protocol",
"crates/ai_toolset",
"crates/ai_usage",
"crates/attachment",
"crates/bot_id",
"crates/bot_token",
+ "crates/broadcast",
+ "crates/channel_sender",
+ "crates/connection_gateway_client",
+ "crates/connection_gateway_models",
"crates/cowlike",
+ "crates/database_env_vars",
"crates/document_sub_type",
+ "crates/entity_access",
+ "crates/entity_access_db_utils",
"crates/genai_telemetry",
"crates/harness_id",
"crates/harness_token",
"crates/image_generation",
+ "crates/initiative",
+ "crates/invite_email",
+ "crates/kafka_util",
+ "crates/last_online_tracker",
+ "crates/lexical_client",
"crates/macro_auth",
"crates/macro_authorization",
"crates/macro_aws_config",
+ "crates/macro_entrypoint",
"crates/macro_env",
"crates/macro_env_var",
+ "crates/macro_event_broker",
+ "crates/macro_event_topics",
+ "crates/macro_service_urls",
+ "crates/macro_tower_layers",
"crates/macro_user_id",
"crates/macro_uuid",
+ "crates/mention_utils",
+ "crates/messages",
"crates/model",
"crates/model-entity",
"crates/model-error-response",
"crates/model_file_type",
+ "crates/model_notifications",
"crates/model_owner",
"crates/model_user",
"crates/models_bulk_upload",
+ "crates/models_entity_access_management",
"crates/models_pagination",
"crates/models_permissions",
+ "crates/models_properties",
"crates/models_sfs",
"crates/non_empty",
+ "crates/notification",
+ "crates/notification_state",
"crates/prompt",
+ "crates/properties",
+ "crates/rate_limit",
"crates/remote_env_var",
+ "crates/share_permission_db_utils",
"crates/static_file_service_client",
+ "crates/system_properties",
"crates/workspace-hack"
],
"image_optimizer": [
diff --git a/Cargo.lock b/Cargo.lock
index cdf284012a..6820b018d3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -9570,6 +9570,8 @@ dependencies = [
"attachment",
"base64 0.22.1",
"bot_id",
+ "image",
+ "lexical_client",
"macro_user_id",
"model",
"model-entity",
diff --git a/apps/docs/AI/mcp/tools/generate-image.mdx b/apps/docs/AI/mcp/tools/generate-image.mdx
index cfcfeaf338..fad1b072e6 100644
--- a/apps/docs/AI/mcp/tools/generate-image.mdx
+++ b/apps/docs/AI/mcp/tools/generate-image.mdx
@@ -1,11 +1,11 @@
---
title: GenerateImage
-description: "Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, embed the returned URL as a Markdown image. Do not cite it as a document. Generation takes several seconds."
+description: "Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, copy the returned markdown verbatim on its own line; it includes dimensions so the image reserves space before loading. Do not cite it as a document. Generation takes several seconds."
---
# GenerateImage
-Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, embed the returned URL as a Markdown image. Do not cite it as a document. Generation takes several seconds.
+Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, copy the returned markdown verbatim on its own line; it includes dimensions so the image reserves space before loading. Do not cite it as a document. Generation takes several seconds.
## Parameters
diff --git a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.test.tsx b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.test.tsx
index 4653053666..15c07dff12 100644
--- a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.test.tsx
+++ b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.test.tsx
@@ -1,3 +1,4 @@
+import type { GenerateImageResponse } from '@service-cognition/generated/tools/types';
import { cleanup, fireEvent, render } from '@solidjs/testing-library';
import { createSignal } from 'solid-js';
import { afterEach, describe, expect, it } from 'vitest';
@@ -10,11 +11,14 @@ const result = {
mimeType: 'image/png',
sizeBytes: 132421,
note: 'A frog under a leaf.',
+ width: 1536,
+ height: 1024,
};
function imageTool(
response = true,
- error?: string | (() => string | undefined)
+ error?: string | (() => string | undefined),
+ data: GenerateImageResponse = result
) {
const failure = () => (typeof error === 'function' ? error() : error);
return render(() => (
@@ -26,9 +30,7 @@ function imageTool(
data: { prompt: 'A frog under a leaf' },
}}
response={
- response
- ? { id: 'call-1', name: 'GenerateImage', data: result }
- : undefined
+ response ? { id: 'call-1', name: 'GenerateImage', data } : undefined
}
chat_id="chat-1"
message_id="message-1"
@@ -65,6 +67,29 @@ describe('generated image result', () => {
expect(view.queryByRole('button')).toBeNull();
});
+ it('reserves the same responsive box before load and after a load failure', () => {
+ const view = imageTool();
+ const image = view.getByRole('img');
+ const frame = image.parentElement!;
+ expect(image.getAttribute('width')).toBe('576');
+ expect(image.getAttribute('height')).toBe('384');
+ expect(frame.style.width).toBe('576px');
+ expect(frame.style.aspectRatio).toBe('576 / 384');
+ const style = frame.getAttribute('style');
+ fireEvent.load(image);
+ expect(frame.getAttribute('style')).toBe(style);
+ fireEvent.error(image);
+ expect(frame.getAttribute('style')).toBe(style);
+ expect(view.getByText('Preview unavailable')).toBeTruthy();
+ });
+
+ it('still renders historical results without dimensions', () => {
+ const { width: _, height: __, ...historical } = result;
+ const view = imageTool(true, undefined, historical);
+ expect(view.getByRole('img').getAttribute('src')).toBe(result.url);
+ expect(view.getByRole('img').hasAttribute('width')).toBe(false);
+ });
+
it('shows a status while generation is pending', () => {
const view = imageTool(false);
expect(view.getByText('Generating image')).toBeTruthy();
diff --git a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx
index d8dfb0c31b..2d7728777f 100644
--- a/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx
+++ b/apps/web/src/lib/core/component/AI/component/tool/GenerateImage.tsx
@@ -1,25 +1,57 @@
+import { constrainImageDimensions } from '@macro-inc/lexical-core/utils/media';
import LoadingSpinner from '@phosphor/spinner.svg';
import { createSignal, Show } from 'solid-js';
import { createToolRenderer, useToolError } from './ToolRenderer';
-function GeneratedImage(props: { url: string }) {
+function GeneratedImage(props: {
+ url: string;
+ width?: number | null;
+ height?: number | null;
+}) {
+ const dimensions = () =>
+ constrainImageDimensions(
+ props.width ?? undefined,
+ props.height ?? undefined,
+ undefined,
+ 384
+ );
const [failedUrl, setFailedUrl] = createSignal<string>();
return (
- <Show
- when={failedUrl() !== props.url}
- fallback={
- <div role="status" class="text-sm text-ink-muted">
- Preview unavailable
- </div>
- }
+ <div
+ class="relative my-2 max-w-full"
+ style={{
+ width: dimensions() ? `${dimensions()!.width}px` : undefined,
+ 'aspect-ratio': dimensions()
+ ? `${dimensions()!.width} / ${dimensions()!.height}`
+ : undefined,
+ }}
>
- <img
- src={props.url}
- alt="Generated image"
- class="my-2 block h-auto max-h-96 w-auto max-w-full rounded-xl"
- onError={() => setFailedUrl(props.url)}
- />
- </Show>
+ <Show
+ when={failedUrl() !== props.url}
+ fallback={
+ <div
+ role="status"
+ class="flex h-full items-center justify-center text-sm text-ink-muted"
+ >
+ Preview unavailable
+ </div>
+ }
+ >
+ <img
+ src={props.url}
+ alt="Generated image"
+ width={dimensions()?.width}
+ height={dimensions()?.height}
+ class="block h-auto max-h-96 w-auto max-w-full rounded-xl"
+ style={
+ dimensions()
+ ? { width: '100%', height: '100%', 'object-fit': 'contain' }
+ : undefined
+ }
+ onError={() => setFailedUrl(props.url)}
+ />
+ </Show>
+ </div>
);
}
@@ -42,7 +74,13 @@ export const generateImageHandler = createToolRenderer({
</div>
}
>
- {(result) => <GeneratedImage url={result().url} />}
+ {(result) => (
+ <GeneratedImage
+ url={result().url}
+ width={result().width}
+ height={result().height}
+ />
+ )}
</Show>
);
},
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.test.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.test.tsx
index 3f0774b68b..0e442e87b4 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.test.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.test.tsx
@@ -2,7 +2,7 @@
* @vitest-environment jsdom
*/
-import { render, screen } from '@solidjs/testing-library';
+import { fireEvent, render, screen } from '@solidjs/testing-library';
import { describe, expect, it, vi } from 'vitest';
const mediaPlugin = vi.hoisted(() => ({
@@ -51,6 +51,38 @@ describe('markdown media loading', () => {
expect(card.className).toContain('aspect-video');
});
+ it('keeps known dimensions on load and failure, including short images', () => {
+ const view = render(() => (
+ <MarkdownImage
+ {...unsetMedia}
+ key="known-image"
+ url="https://files.macro.com/banner.png"
+ alt="banner"
+ width={2048}
+ height={512}
+ constrainedWidth={400}
+ constrainedHeight={400}
+ />
+ ));
+ const image = view.container.querySelector('img')!;
+ const frame = image.parentElement!;
+ expect(frame.style.aspectRatio).toBe('4');
+ expect(frame.style.width).toBe('100%');
+ expect(frame.style.maxWidth).toBe('400px');
+ expect(image.classList.contains('absolute')).toBe(true);
+ const initialStyle = frame.getAttribute('style');
+ Object.defineProperties(image, {
+ naturalWidth: { value: 2048 },
+ naturalHeight: { value: 512 },
+ });
+ fireEvent.load(image);
+ expect(frame.getAttribute('style')).toBe(initialStyle);
+ fireEvent.error(image);
+ expect(frame.getAttribute('style')).toBe(initialStyle);
+ expect(frame.classList.contains('min-h-44')).toBe(false);
+ expect(view.getByText('This image could not be found.')).toBeTruthy();
+ });
+
it('shows a reserved video card named from the url', () => {
render(() => (
<MarkdownVideo
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.tsx
index 4b2898a6a9..69aa711961 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/MarkdownImage.tsx
@@ -269,12 +269,13 @@ export function MarkdownImage(props: ImageDecoratorProps) {
class={cn(
'relative max-w-full my-4 grid place-items-center',
isSelectedAsNode() && 'ring-3 ring-edge-muted',
- state() === 'error' &&
- 'pattern-edge-muted pattern-diagonal-8 min-h-44',
+ state() === 'error' && 'pattern-edge-muted pattern-diagonal-8',
+ state() === 'error' && !effectiveDims()[0] && 'min-h-44',
// If there are no constrained dimensions, center the image
!props.constrainedWidth && !props.constrainedHeight && 'mx-auto'
)}
style={{
+ width: effectiveDims()[0] ? '100%' : undefined,
'max-width': `${effectiveDims()[0] ? effectiveDims()[0] * scale() : 640}px`,
'aspect-ratio':
effectiveDims()[0] && effectiveDims()[1]
@@ -317,6 +318,7 @@ export function MarkdownImage(props: ImageDecoratorProps) {
crossorigin="anonymous"
class={cn(
'h-full object-contain',
+ effectiveDims()[0] > 0 && 'absolute inset-0 size-full',
(state() === 'loading' || state() === 'error') && 'invisible',
state() === 'loading' &&
!effectiveDims()[0] &&
@@ -327,14 +329,12 @@ export function MarkdownImage(props: ImageDecoratorProps) {
ref={imageRef}
src={imageUrl()}
style={{
- width: effectiveDims()[0]
- ? `${effectiveDims()[0] * scale()}px`
- : 'auto',
+ width: effectiveDims()[0] ? '100%' : 'auto',
}}
/>
<Show when={state() === 'error'}>
- <div class="absolute top-0 left-0 size-full flex flex-col justify-center items-center gap-2 text-ink-extra-muted min-h-44">
+ <div class="absolute top-0 left-0 size-full flex flex-col justify-center items-center gap-2 text-ink-extra-muted">
<ImageIcon class="size-5" />
<div>{ImageErrors[imageError() ?? 'FALLBACK']}</div>
</div>
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
index d50cbb59ab..bc2567907b 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
@@ -3758,6 +3758,9 @@ export const GenerateImageResponse = z.object({
url: z.string(),
mimeType: z.string(),
sizeBytes: z.number().int().gte(0),
+ width: z.union([z.number().int().gte(0), z.null()]).optional(),
+ height: z.union([z.number().int().gte(0), z.null()]).optional(),
+ markdown: z.union([z.string(), z.null()]).optional(),
note: z.union([z.string(), z.null()]).optional(),
});
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
index f476f6b061..cb074547e4 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
@@ -4527,7 +4527,7 @@ export interface EditTagResponse {
summary: string;
}
/**
- * Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, embed the returned URL as a Markdown image. Do not cite it as a document. Generation takes several seconds.
+ * Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, copy the returned markdown verbatim on its own line; it includes dimensions so the image reserves space before loading. Do not cite it as a document. Generation takes several seconds.
*/
export interface GenerateImage {
/**
@@ -4570,6 +4570,18 @@ export interface GenerateImageResponse {
* Size of the image in bytes.
*/
sizeBytes: number;
+ /**
+ * Intrinsic pixel width. Absent only in historical tool results.
+ */
+ width?: number | null;
+ /**
+ * Intrinsic pixel height. Absent only in historical tool results.
+ */
+ height?: number | null;
+ /**
+ * Ready-to-send channel image markup with dimensions. Copy verbatim on its own line.
+ */
+ markdown?: string | null;
/**
* Commentary the model produced alongside the image, when any.
*/
diff --git a/crates/ai_tools/src/tool_context/images.rs b/crates/ai_tools/src/tool_context/images.rs
index a37ffe9c62..d6b0629928 100644
--- a/crates/ai_tools/src/tool_context/images.rs
+++ b/crates/ai_tools/src/tool_context/images.rs
@@ -77,6 +77,11 @@ fn build_with_cdn(
image_generation::domain::service::ImageGenerationServiceImpl::new(
generator,
image_generation::outbound::static_files::StaticFileImageStore::new(storage),
+ Arc::new(
+ image_generation::outbound::lexical::LexicalImageMarkdownComposer::new(
+ documents.lexical_client.clone(),
+ ),
+ ),
)
.with_reference_reader(references),
documents.actor,
diff --git a/crates/image_generation/Cargo.toml b/crates/image_generation/Cargo.toml
index b5a8d5c747..71ec81d4d2 100644
--- a/crates/image_generation/Cargo.toml
+++ b/crates/image_generation/Cargo.toml
@@ -11,6 +11,8 @@ async-trait.workspace = true
attachment = { path = "../attachment" }
base64.workspace = true
bot_id = { path = "../bot_id" }
+image.workspace = true
+lexical_client = { path = "../lexical_client" }
model = { path = "../model" }
model-entity = { path = "../model-entity" }
model_owner = { path = "../model_owner" }
diff --git a/crates/image_generation/src/domain/models.rs b/crates/image_generation/src/domain/models.rs
index 3b916d2e05..8b81140aa8 100644
--- a/crates/image_generation/src/domain/models.rs
+++ b/crates/image_generation/src/domain/models.rs
@@ -94,6 +94,10 @@ pub struct GeneratedImage {
pub bytes: Vec<u8>,
/// IANA media type of `bytes`, e.g. `image/png`.
pub mime_type: String,
+ /// Intrinsic pixel width of the generated image.
+ pub width: u32,
+ /// Intrinsic pixel height of the generated image.
+ pub height: u32,
/// Any commentary the model produced alongside the image.
pub note: Option<String>,
}
@@ -151,12 +155,18 @@ pub struct NewGeneratedImage {
/// A generated image stored in static file service.
#[derive(Debug)]
pub struct StoredGeneratedImage {
+ /// Dimension-preserving channel markup composed by the editor service.
+ pub markdown: String,
/// The stored static file.
pub static_file: StoredImage,
/// IANA media type of the stored bytes.
pub mime_type: String,
/// Number of stored bytes.
pub size_bytes: usize,
+ /// Intrinsic pixel width of the generated image.
+ pub width: u32,
+ /// Intrinsic pixel height of the generated image.
+ pub height: u32,
/// Any commentary the model produced alongside the image.
pub note: Option<String>,
}
@@ -176,6 +186,9 @@ pub enum GenerateImageError {
/// The image was generated but not stored.
#[error(transparent)]
Storage(#[from] SaveImageError),
+ /// The saved image could not be composed into channel markup.
+ #[error(transparent)]
+ Markup(#[from] ComposeImageError),
}
/// Generated bytes and media type to persist in static file service.
@@ -202,3 +215,8 @@ pub enum SaveImageError {
#[error("could not save the generated image: {0}")]
Internal(rootcause::Report),
}
+
+/// Failure to compose a saved image through the editor service.
+#[derive(Debug, thiserror::Error)]
+#[error("could not compose image markup: {0}")]
+pub struct ComposeImageError(pub rootcause::Report);
diff --git a/crates/image_generation/src/domain/ports.rs b/crates/image_generation/src/domain/ports.rs
index f291f80467..14dc704323 100644
--- a/crates/image_generation/src/domain/ports.rs
+++ b/crates/image_generation/src/domain/ports.rs
@@ -74,3 +74,15 @@ pub trait ImageGenerationService: Send + Sync {
image: NewGeneratedImage,
) -> impl Future<Output = Result<StoredGeneratedImage, GenerateImageError>> + Send;
}
+
+/// Composes saved images using the editor's serialization contract.
+#[async_trait::async_trait]
+pub trait ImageMarkdownComposer: Send + Sync {
+ /// Return channel markup that preserves the intrinsic image dimensions.
+ async fn compose_image(
+ &self,
+ image: &StoredImage,
+ width: u32,
+ height: u32,
+ ) -> Result<String, super::models::ComposeImageError>;
+}
diff --git a/crates/image_generation/src/domain/service.rs b/crates/image_generation/src/domain/service.rs
index f027e1c775..2f89196ed6 100644
--- a/crates/image_generation/src/domain/service.rs
+++ b/crates/image_generation/src/domain/service.rs
@@ -5,8 +5,8 @@ use super::models::{
StoredGeneratedImage,
};
use super::ports::{
- ImageGenerationService, ImageGenerator, ImageReferenceReader, ImageStore,
- UnconfiguredImageReferenceReader,
+ ImageGenerationService, ImageGenerator, ImageMarkdownComposer, ImageReferenceReader,
+ ImageStore, UnconfiguredImageReferenceReader,
};
use model_owner::CreationPrincipal;
use std::sync::Arc;
@@ -14,19 +14,25 @@ use std::sync::Arc;
#[cfg(test)]
mod test;
-/// Image generation use case composed from a model provider and static file store.
+/// Image generation use case composed from a provider, static file store, and markup composer.
pub struct ImageGenerationServiceImpl<Store, References = UnconfiguredImageReferenceReader> {
generator: Arc<dyn ImageGenerator>,
store: Store,
+ composer: Arc<dyn ImageMarkdownComposer>,
references: References,
}
impl<Store> ImageGenerationServiceImpl<Store> {
- /// Compose the provider and image-saving capability.
- pub fn new(generator: Arc<dyn ImageGenerator>, store: Store) -> Self {
+ /// Compose the provider, image-saving capability, and markup serializer.
+ pub fn new(
+ generator: Arc<dyn ImageGenerator>,
+ store: Store,
+ composer: Arc<dyn ImageMarkdownComposer>,
+ ) -> Self {
Self {
generator,
store,
+ composer,
references: UnconfiguredImageReferenceReader,
}
}
@@ -38,6 +44,7 @@ impl<Store, References> ImageGenerationServiceImpl<Store, References> {
ImageGenerationServiceImpl {
generator: self.generator,
store: self.store,
+ composer: self.composer,
references,
}
}
@@ -128,10 +135,18 @@ impl<Store: ImageStore, References: ImageReferenceReader> ImageGenerationService
})
.await?;
+ let markdown = self
+ .composer
+ .compose_image(&static_file, generated.width, generated.height)
+ .await?;
+
Ok(StoredGeneratedImage {
+ markdown,
static_file,
mime_type: generated.mime_type,
size_bytes,
+ width: generated.width,
+ height: generated.height,
note: generated.note,
})
}
diff --git a/crates/image_generation/src/domain/service/test.rs b/crates/image_generation/src/domain/service/test.rs
index 2b7f36a648..12d042a220 100644
--- a/crates/image_generation/src/domain/service/test.rs
+++ b/crates/image_generation/src/domain/service/test.rs
@@ -77,8 +77,44 @@ impl ImageGenerator for FakeGenerator {
}
}
+#[derive(Default)]
+struct RecordingComposer {
+ calls: Mutex<Vec<(Uuid, String, u32, u32)>>,
+ fail: bool,
+}
+
+#[async_trait::async_trait]
+impl ImageMarkdownComposer for RecordingComposer {
+ async fn compose_image(
+ &self,
+ image: &StoredImage,
+ width: u32,
+ height: u32,
+ ) -> Result<String, crate::domain::models::ComposeImageError> {
+ self.calls
+ .lock()
+ .unwrap()
+ .push((image.id, image.url.clone(), width, height));
+ if self.fail {
+ return Err(crate::domain::models::ComposeImageError(
+ rootcause::report!("lexical unavailable"),
+ ));
+ }
+ Ok("markup returned by Lexical".to_string())
+ }
+}
+
+fn test_service(
+ generator: Arc<dyn ImageGenerator>,
+ store: Arc<RecordingStore>,
+) -> ImageGenerationServiceImpl<Arc<RecordingStore>> {
+ ImageGenerationServiceImpl::new(generator, store, Arc::new(RecordingComposer::default()))
+}
+
fn png() -> GeneratedImage {
GeneratedImage {
+ width: 1536,
+ height: 1024,
bytes: PNG.to_vec(),
mime_type: "image/png".to_string(),
note: Some("A calm scene.".to_string()),
@@ -97,7 +133,7 @@ fn request(prompt: &str) -> NewGeneratedImage {
async fn generates_then_uploads_bytes_and_returns_the_static_file() {
let store = Arc::new(RecordingStore::default());
let generator = Arc::new(FakeGenerator::returning(png()));
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone());
+ let service = test_service(generator.clone(), store.clone());
let created = service
.create_generated_image(&principal(), request(" a lighthouse at dusk "))
.await
@@ -105,6 +141,7 @@ async fn generates_then_uploads_bytes_and_returns_the_static_file() {
assert_eq!(created.static_file.id, STATIC_FILE_ID);
assert_eq!(created.static_file.url, "https://static.example/file/image");
assert_eq!(created.mime_type, "image/png");
+ assert_eq!((created.width, created.height), (1536, 1024));
assert_eq!(created.size_bytes, PNG.len());
assert_eq!(created.note.as_deref(), Some("A calm scene."));
assert_eq!(
@@ -125,7 +162,7 @@ async fn generates_then_uploads_bytes_and_returns_the_static_file() {
async fn rejects_bad_input_before_calling_the_provider() {
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone());
+ let service = test_service(generator.clone(), store.clone());
for image in [request(" "), request(&"p".repeat(MAX_PROMPT_BYTES + 1))] {
assert!(matches!(
service.create_generated_image(&principal(), image).await,
@@ -139,7 +176,7 @@ async fn rejects_bad_input_before_calling_the_provider() {
#[tokio::test]
async fn provider_failures_upload_no_image() {
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(
+ let service = test_service(
Arc::new(FakeGenerator::refusing("blocked by safety filters")),
store.clone(),
);
@@ -147,8 +184,7 @@ async fn provider_failures_upload_no_image() {
matches!(service.create_generated_image(&principal(), request("prompt")).await,
Err(GenerateImageError::Generation(ImageGenerationError::Refused(ref reason))) if reason == "blocked by safety filters")
);
- let service =
- ImageGenerationServiceImpl::new(Arc::new(UnconfiguredImageGenerator), store.clone());
+ let service = test_service(Arc::new(UnconfiguredImageGenerator), store.clone());
assert!(matches!(
service
.create_generated_image(&principal(), request("prompt"))
@@ -167,10 +203,7 @@ async fn provider_failures_upload_no_image() {
..png()
},
] {
- let service = ImageGenerationServiceImpl::new(
- Arc::new(FakeGenerator::returning(image)),
- store.clone(),
- );
+ let service = test_service(Arc::new(FakeGenerator::returning(image)), store.clone());
assert!(matches!(
service
.create_generated_image(&principal(), request("prompt"))
@@ -185,7 +218,7 @@ async fn provider_failures_upload_no_image() {
#[tokio::test]
async fn propagates_static_file_upload_failures() {
- let service = ImageGenerationServiceImpl::new(
+ let service = test_service(
Arc::new(FakeGenerator::returning(png())),
Arc::new(RecordingStore {
fail: true,
@@ -250,8 +283,8 @@ async fn resolves_references_in_order_under_the_creating_principal_before_genera
));
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone())
- .with_reference_reader(reader.clone());
+ let service =
+ test_service(generator.clone(), store.clone()).with_reference_reader(reader.clone());
let mut image = request(" edit image 1 using image 2 ");
image.reference_images = vec![DOCUMENT_REFERENCE, STATIC_REFERENCE];
@@ -287,8 +320,8 @@ async fn excessive_reference_count_is_rejected_before_any_read_or_generation() {
let reader = Arc::new(RecordingReader::returning(Vec::new()));
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone())
- .with_reference_reader(reader.clone());
+ let service =
+ test_service(generator.clone(), store.clone()).with_reference_reader(reader.clone());
let mut image = request("edit these images");
image.reference_images = vec![DOCUMENT_REFERENCE; MAX_REFERENCE_IMAGES + 1];
@@ -316,8 +349,8 @@ async fn failed_reference_reads_never_generate_from_a_partial_set() {
]));
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone())
- .with_reference_reader(reader.clone());
+ let service =
+ test_service(generator.clone(), store.clone()).with_reference_reader(reader.clone());
let mut image = request("combine all three images");
image.reference_images = vec![DOCUMENT_REFERENCE, STATIC_REFERENCE, DOCUMENT_REFERENCE];
@@ -351,8 +384,8 @@ async fn invalid_reference_content_is_rejected_before_generation_or_storage() {
));
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone())
- .with_reference_reader(reader.clone());
+ let service =
+ test_service(generator.clone(), store.clone()).with_reference_reader(reader.clone());
let mut image = request("edit these images");
image.reference_images = vec![DOCUMENT_REFERENCE; image_count];
@@ -378,8 +411,7 @@ async fn accepts_three_supported_images_at_the_total_byte_limit() {
));
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone())
- .with_reference_reader(reader);
+ let service = test_service(generator.clone(), store.clone()).with_reference_reader(reader);
let mut image = request("combine all three images");
image.reference_images = vec![DOCUMENT_REFERENCE, STATIC_REFERENCE, DOCUMENT_REFERENCE];
@@ -406,7 +438,7 @@ async fn accepts_three_supported_images_at_the_total_byte_limit() {
async fn missing_reference_reader_does_not_silently_fall_back_to_text_only() {
let generator = Arc::new(FakeGenerator::returning(png()));
let store = Arc::new(RecordingStore::default());
- let service = ImageGenerationServiceImpl::new(generator.clone(), store.clone());
+ let service = test_service(generator.clone(), store.clone());
let mut image = request("edit this photo");
image.reference_images = vec![DOCUMENT_REFERENCE];
@@ -417,3 +449,43 @@ async fn missing_reference_reader_does_not_silently_fall_back_to_text_only() {
assert!(generator.requests.lock().unwrap().is_empty());
assert!(store.saves.lock().unwrap().is_empty());
}
+
+#[tokio::test]
+async fn delegates_saved_image_dimensions_to_the_composer() {
+ let store = Arc::new(RecordingStore::default());
+ let composer = Arc::new(RecordingComposer::default());
+ let service = ImageGenerationServiceImpl::new(
+ Arc::new(FakeGenerator::returning(png())),
+ store,
+ composer.clone(),
+ );
+ let created = service
+ .create_generated_image(&principal(), request("image"))
+ .await
+ .unwrap();
+ assert_eq!(created.markdown, "markup returned by Lexical");
+ assert_eq!(
+ *composer.calls.lock().unwrap(),
+ [(STATIC_FILE_ID, created.static_file.url, 1536, 1024)]
+ );
+}
+
+#[tokio::test]
+async fn reports_composition_failure_after_saving_the_image() {
+ let store = Arc::new(RecordingStore::default());
+ let service = ImageGenerationServiceImpl::new(
+ Arc::new(FakeGenerator::returning(png())),
+ store.clone(),
+ Arc::new(RecordingComposer {
+ fail: true,
+ ..Default::default()
+ }),
+ );
+ assert!(matches!(
+ service
+ .create_generated_image(&principal(), request("image"))
+ .await,
+ Err(GenerateImageError::Markup(_))
+ ));
+ assert_eq!(store.saves.lock().unwrap().len(), 1);
+}
diff --git a/crates/image_generation/src/inbound/toolset/generate_image.rs b/crates/image_generation/src/inbound/toolset/generate_image.rs
index aeec6135ea..d5865cc032 100644
--- a/crates/image_generation/src/inbound/toolset/generate_image.rs
+++ b/crates/image_generation/src/inbound/toolset/generate_image.rs
@@ -13,7 +13,7 @@ use super::ImageGenerationToolContext;
use crate::domain::{
models::{
GenerateImageError, ImageAspectRatio, ImageGenerationError, ImageReference,
- NewGeneratedImage, ReadImageError,
+ NewGeneratedImage, ReadImageError, StoredGeneratedImage,
},
ports::ImageGenerationService,
};
@@ -76,7 +76,7 @@ impl From<ImageReferenceInput> for ImageReference {
#[serde(rename_all = "camelCase")]
#[schemars(
title = "GenerateImage",
- description = "Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, embed the returned URL as a Markdown image. Do not cite it as a document. Generation takes several seconds."
+ description = "Generate or edit an image with Google's Nano Banana image model and save the result in static file service. Use for pictures, illustrations, diagram concepts, logo ideas, mockups, or edits based on reference photos. When the user supplies photos or asks to modify an existing image, pass them in referenceImages; describing a photo in the prompt alone does not send it to the image model. Describe the subject, style, composition, lighting, and any text to render; only the prompt is required. Refer to reference images by their order (image 1, image 2, image 3) when explaining how to use them. Returns the static file ID and image URL. The tool displays the image inline in chat. In channel messages without tool cards, copy the returned markdown verbatim on its own line; it includes dimensions so the image reserves space before loading. Do not cite it as a document. Generation takes several seconds."
)]
/// Generate an image and save it as a static file.
pub struct GenerateImage {
@@ -109,6 +109,15 @@ pub struct GenerateImageResponse {
pub mime_type: String,
/// Size of the image in bytes.
pub size_bytes: usize,
+ /// Intrinsic pixel width. Absent only in historical tool results.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub width: Option<u32>,
+ /// Intrinsic pixel height. Absent only in historical tool results.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub height: Option<u32>,
+ /// Ready-to-send channel image markup with dimensions. Copy verbatim on its own line.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub markdown: Option<String>,
/// Commentary the model produced alongside the image, when any.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub note: Option<String>,
@@ -135,6 +144,9 @@ fn generate_error(error: GenerateImageError) -> ToolCallError {
GenerateImageError::Generation(ImageGenerationError::Provider(_)) => {
"the image model request failed; try again shortly".to_string()
}
+ GenerateImageError::Markup(_) => {
+ "the image was saved but its channel markup could not be composed".to_string()
+ }
GenerateImageError::Storage(_) => {
"the image was generated but could not be saved to Macro".to_string()
}
@@ -179,12 +191,21 @@ where
.await
.map_err(generate_error)?;
- Ok(GenerateImageResponse {
+ Ok(created.into())
+ }
+}
+
+impl From<StoredGeneratedImage> for GenerateImageResponse {
+ fn from(created: StoredGeneratedImage) -> Self {
+ Self {
static_file_id: created.static_file.id.to_string(),
url: created.static_file.url,
mime_type: created.mime_type,
size_bytes: created.size_bytes,
+ width: Some(created.width),
+ height: Some(created.height),
+ markdown: Some(created.markdown),
note: created.note,
- })
+ }
}
}
diff --git a/crates/image_generation/src/inbound/toolset/generate_image/test.rs b/crates/image_generation/src/inbound/toolset/generate_image/test.rs
index a74e1ad58d..db798edf46 100644
--- a/crates/image_generation/src/inbound/toolset/generate_image/test.rs
+++ b/crates/image_generation/src/inbound/toolset/generate_image/test.rs
@@ -147,6 +147,9 @@ fn response_omits_an_absent_note() {
url: "https://static.example/file/image".to_string(),
mime_type: "image/png".to_string(),
size_bytes: 3,
+ width: Some(1536),
+ height: Some(1024),
+ markdown: None,
note: None,
})
.unwrap();
@@ -156,7 +159,31 @@ fn response_omits_an_absent_note() {
"staticFileId": "file",
"url": "https://static.example/file/image",
"mimeType": "image/png",
- "sizeBytes": 3
+ "sizeBytes": 3,
+ "width": 1536,
+ "height": 1024
})
);
}
+
+#[test]
+fn response_forwards_markup_from_the_service() {
+ let response = GenerateImageResponse::from(StoredGeneratedImage {
+ static_file: crate::domain::models::StoredImage {
+ id: uuid::Uuid::from_u128(123),
+ url: "https://static.example/file/image".to_string(),
+ },
+ mime_type: "image/png".to_string(),
+ size_bytes: 100,
+ width: 1536,
+ height: 1024,
+ markdown: "markup returned by Lexical".to_string(),
+ note: None,
+ });
+ assert_eq!(
+ response.markdown.as_deref(),
+ Some("markup returned by Lexical")
+ );
+ assert_eq!(response.width, Some(1536));
+ assert_eq!(response.height, Some(1024));
+}
diff --git a/crates/image_generation/src/outbound.rs b/crates/image_generation/src/outbound.rs
index dbb3fe6884..a557cbe4da 100644
--- a/crates/image_generation/src/outbound.rs
+++ b/crates/image_generation/src/outbound.rs
@@ -1,4 +1,5 @@
//! Provider and static file storage adapters.
pub mod gemini;
+pub mod lexical;
pub mod references;
pub mod static_files;
diff --git a/crates/image_generation/src/outbound/gemini.rs b/crates/image_generation/src/outbound/gemini.rs
index d21ef20834..57cff16869 100644
--- a/crates/image_generation/src/outbound/gemini.rs
+++ b/crates/image_generation/src/outbound/gemini.rs
@@ -224,7 +224,23 @@ impl GenerateContentResponse {
.decode(data.data.as_bytes())
.context("Gemini image data is not valid base64")
.map_err(ImageGenerationError::Provider)?;
+ let (width, height) = image::ImageReader::new(std::io::Cursor::new(&bytes))
+ .with_guessed_format()
+ .context("could not identify generated image format")
+ .and_then(|reader| {
+ reader
+ .into_dimensions()
+ .context("could not read generated image dimensions")
+ })
+ .map_err(ImageGenerationError::Provider)?;
+ if width == 0 || height == 0 {
+ return Err(ImageGenerationError::Provider(anyhow::anyhow!(
+ "generated image dimensions must be positive"
+ )));
+ }
Ok(GeneratedImage {
+ width,
+ height,
bytes,
mime_type: data.mime_type,
note,
diff --git a/crates/image_generation/src/outbound/gemini/test.rs b/crates/image_generation/src/outbound/gemini/test.rs
index 421644efd5..4f7922c4af 100644
--- a/crates/image_generation/src/outbound/gemini/test.rs
+++ b/crates/image_generation/src/outbound/gemini/test.rs
@@ -3,7 +3,16 @@ use crate::domain::models::{ImageAspectRatio, ReferenceImage};
use wiremock::matchers::{body_json, header, method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};
-const PNG: &[u8] = b"\x89PNG\r\n\x1a\nfake";
+fn image_bytes(format: image::ImageFormat) -> Vec<u8> {
+ let mut bytes = std::io::Cursor::new(Vec::new());
+ image::DynamicImage::new_rgb8(96, 64)
+ .write_to(&mut bytes, format)
+ .unwrap();
+ bytes.into_inner()
+}
+
+static PNG: std::sync::LazyLock<Vec<u8>> =
+ std::sync::LazyLock::new(|| image_bytes(image::ImageFormat::Png));
fn generator(server: &MockServer) -> GeminiImageGenerator {
GeminiImageGenerator::new("test-key".to_string()).with_base_url(server.uri())
@@ -40,7 +49,7 @@ async fn posts_the_prompt_and_decodes_the_first_inline_image() {
.respond_with(ResponseTemplate::new(200).set_body_json(image_response(
serde_json::json!([
{ "text": " Here is your lighthouse. " },
- { "inlineData": { "mimeType": "image/png", "data": base64::engine::general_purpose::STANDARD.encode(PNG) } },
+ { "inlineData": { "mimeType": "image/png", "data": base64::engine::general_purpose::STANDARD.encode(&*PNG) } },
{ "inlineData": { "mimeType": "image/jpeg", "data": "AAAA" } }
]),
)))
@@ -53,7 +62,8 @@ async fn posts_the_prompt_and_decodes_the_first_inline_image() {
.await
.unwrap();
- assert_eq!(image.bytes, PNG);
+ assert_eq!(image.bytes, *PNG);
+ assert_eq!((image.width, image.height), (96, 64));
assert_eq!(image.mime_type, "image/png");
assert_eq!(image.note.as_deref(), Some("Here is your lighthouse."));
}
@@ -74,7 +84,7 @@ async fn posts_ordered_reference_images_with_their_mime_types_and_exact_bytes()
{
"inlineData": {
"mimeType": "image/png",
- "data": base64::engine::general_purpose::STANDARD.encode(PNG),
+ "data": base64::engine::general_purpose::STANDARD.encode(&*PNG),
}
},
{
@@ -96,7 +106,7 @@ async fn posts_ordered_reference_images_with_their_mime_types_and_exact_bytes()
{
"inlineData": {
"mimeType": "image/png",
- "data": base64::engine::general_purpose::STANDARD.encode(PNG),
+ "data": base64::engine::general_purpose::STANDARD.encode(&*PNG),
}
},
]))),
@@ -123,7 +133,8 @@ async fn posts_ordered_reference_images_with_their_mime_types_and_exact_bytes()
.await
.unwrap();
- assert_eq!(image.bytes, PNG);
+ assert_eq!(image.bytes, *PNG);
+ assert_eq!((image.width, image.height), (96, 64));
assert_eq!(image.mime_type, "image/png");
assert_eq!(image.note.as_deref(), Some("Here is the edited image."));
}
@@ -133,7 +144,7 @@ async fn omits_image_config_without_an_aspect_ratio() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.respond_with(ResponseTemplate::new(200).set_body_json(image_response(
- serde_json::json!([{ "inlineData": { "mimeType": "image/png", "data": "AAAA" } }]),
+ serde_json::json!([{ "inlineData": { "mimeType": "image/png", "data": base64::engine::general_purpose::STANDARD.encode(&*PNG) } }]),
)))
.mount(&server)
.await;
@@ -245,3 +256,36 @@ async fn invalid_base64_is_a_provider_error() {
ImageGenerationError::Provider(_)
));
}
+
+#[test]
+fn reads_actual_dimensions_for_supported_image_formats() {
+ for (format, mime) in [
+ (image::ImageFormat::Png, "image/png"),
+ (image::ImageFormat::Jpeg, "image/jpeg"),
+ (image::ImageFormat::WebP, "image/webp"),
+ (image::ImageFormat::Gif, "image/gif"),
+ ] {
+ let response: GenerateContentResponse =
+ serde_json::from_value(image_response(serde_json::json!([{ "inlineData": {
+ "mimeType": mime,
+ "data": base64::engine::general_purpose::STANDARD.encode(image_bytes(format)),
+ }}])))
+ .unwrap();
+ let image = response.into_image().unwrap();
+ assert_eq!((image.width, image.height), (96, 64), "{mime}");
+ }
+}
+
+#[test]
+fn rejects_image_bytes_without_readable_dimensions() {
+ let response: GenerateContentResponse =
+ serde_json::from_value(image_response(serde_json::json!([{ "inlineData": {
+ "mimeType": "image/png",
+ "data": base64::engine::general_purpose::STANDARD.encode(b"not an image"),
+ }}])))
+ .unwrap();
+ assert!(matches!(
+ response.into_image(),
+ Err(ImageGenerationError::Provider(_))
+ ));
+}
diff --git a/crates/image_generation/src/outbound/lexical.rs b/crates/image_generation/src/outbound/lexical.rs
new file mode 100644
index 0000000000..eb9a2caa9b
--- /dev/null
+++ b/crates/image_generation/src/outbound/lexical.rs
@@ -0,0 +1,43 @@
+//! Image markup composition through the Lexical service.
+use crate::domain::{
+ models::{ComposeImageError, StoredImage},
+ ports::ImageMarkdownComposer,
+};
+use lexical_client::{LexicalClient, parse_markdown::ImageMarkdownRequest};
+use std::sync::Arc;
+
+/// Adapter delegating image serialization to the owning editor service.
+pub struct LexicalImageMarkdownComposer {
+ client: Arc<LexicalClient>,
+}
+
+impl LexicalImageMarkdownComposer {
+ /// Use the host's authenticated Lexical service client.
+ pub fn new(client: Arc<LexicalClient>) -> Self {
+ Self { client }
+ }
+}
+
+#[async_trait::async_trait]
+impl ImageMarkdownComposer for LexicalImageMarkdownComposer {
+ #[tracing::instrument(skip_all, err)]
+ async fn compose_image(
+ &self,
+ image: &StoredImage,
+ width: u32,
+ height: u32,
+ ) -> Result<String, ComposeImageError> {
+ self.client
+ .compose_image_markdown(&ImageMarkdownRequest {
+ static_file_id: &image.id.to_string(),
+ url: &image.url,
+ width,
+ height,
+ })
+ .await
+ .map_err(|error| ComposeImageError(rootcause::report!(error).into()))
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/image_generation/src/outbound/lexical/test.rs b/crates/image_generation/src/outbound/lexical/test.rs
new file mode 100644
index 0000000000..7e3cd4b853
--- /dev/null
+++ b/crates/image_generation/src/outbound/lexical/test.rs
@@ -0,0 +1,46 @@
+use super::*;
+use wiremock::{
+ Mock, MockServer, ResponseTemplate,
+ matchers::{body_json, header, method, path},
+};
+
+#[tokio::test]
+async fn delegates_dimensions_and_identity_to_authenticated_lexical_endpoint() {
+ let server = MockServer::start().await;
+ let image = StoredImage {
+ id: uuid::Uuid::from_u128(123),
+ url: "https://static.example/file/image".to_string(),
+ };
+ Mock::given(method("POST"))
+ .and(path("/image-markdown"))
+ .and(header("x-internal-auth-key", "test-key"))
+ .and(body_json(serde_json::json!({ "staticFileId": image.id, "url": image.url, "width": 1536, "height": 1024 })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ "markdown": "serialized by Lexical" })))
+ .expect(1).mount(&server).await;
+ let composer = LexicalImageMarkdownComposer::new(Arc::new(LexicalClient::new(
+ "test-key".to_string(),
+ server.uri(),
+ )));
+ assert_eq!(
+ composer.compose_image(&image, 1536, 1024).await.unwrap(),
+ "serialized by Lexical"
+ );
+}
+
+#[tokio::test]
+async fn propagates_lexical_failures_without_fabricating_markup() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .respond_with(ResponseTemplate::new(503))
+ .mount(&server)
+ .await;
+ let composer = LexicalImageMarkdownComposer::new(Arc::new(LexicalClient::new(
+ "test-key".to_string(),
+ server.uri(),
+ )));
+ let image = StoredImage {
+ id: uuid::Uuid::from_u128(123),
+ url: "https://static.example/file/image".to_string(),
+ };
+ assert!(composer.compose_image(&image, 1536, 1024).await.is_err());
+}
diff --git a/crates/lexical_client/src/parse_markdown.rs b/crates/lexical_client/src/parse_markdown.rs
index a0f1db3eee..279c65f5c6 100644
--- a/crates/lexical_client/src/parse_markdown.rs
+++ b/crates/lexical_client/src/parse_markdown.rs
@@ -130,6 +130,20 @@ struct MentionsResponse {
mentions: Vec<ExtractedMention>,
}
+/// A static image to serialize through Lexical's image node and markdown transformer.
+#[derive(Debug, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ImageMarkdownRequest<'a> {
+ /// Static file capability identifier.
+ pub static_file_id: &'a str,
+ /// Permanent image URL.
+ pub url: &'a str,
+ /// Intrinsic pixel width.
+ pub width: u32,
+ /// Intrinsic pixel height.
+ pub height: u32,
+}
+
/// The Magic Chip embedded in an agent-session announcement, in the shape the
/// lexical service `/agent-announcement` endpoint validates.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
@@ -616,6 +630,22 @@ impl LexicalClient {
Ok(data.mentions)
}
+ /// Compose dimension-preserving channel markup from a real Lexical image node.
+ #[tracing::instrument(skip_all, err)]
+ pub async fn compose_image_markdown(&self, image: &ImageMarkdownRequest<'_>) -> Result<String> {
+ let response = check_response(
+ self.client
+ .post(format!("{}/image-markdown", self.url))
+ .json(image)
+ .send()
+ .await?,
+ )
+ .await?;
+ let data: AgentAnnouncementResponse =
+ response.json().await.context("unexpected response")?;
+ Ok(data.markdown)
+ }
+
/// Composes the channel message announcing an agent session — a structured
/// reply target above the session's Magic Chip — via the lexical service,
/// so the markdown is built from real Lexical nodes.
diff --git a/crates/prompt/src/tool_usage.rs b/crates/prompt/src/tool_usage.rs
index 7daeec6aab..6f3fabfcc2 100644
--- a/crates/prompt/src/tool_usage.rs
+++ b/crates/prompt/src/tool_usage.rs
@@ -32,7 +32,7 @@ when the user explicitely asks you to _execute_ code.
(which creates a file for the code execution environment) for the `CreateDocument` tool which creates a document in the
users workspace. If the user asks you to create a document, write a code file, or create any file you should use the `CreateDocument` tool.
-- To make a picture (illustration, photo-style image, logo concept, mockup, diagram concept), use `GenerateImage`. It renders the prompt with an image model and saves the result to static file service. The tool renders the image inline in chat. In channel messages or other surfaces without tool cards, embed the returned URL as a Markdown image. Never cite the result as a document. Use the returned staticFileId for subsequent edits. `CreateDocument` cannot produce image bytes.
+- To make a picture (illustration, photo-style image, logo concept, mockup, diagram concept), use `GenerateImage`. It renders the prompt with an image model and saves the result to static file service. The tool renders the image inline in chat. In channel messages or other surfaces without tool cards, copy the returned markdown verbatim on its own line. It includes the image dimensions to reserve space before loading; do not replace it with a plain Markdown image URL. Never cite the result as a document. Use the returned staticFileId for subsequent edits. `CreateDocument` cannot produce image bytes.
- `CreateDocument` content (for Markdown documents) is rendered with the same Markdown parser as your chat responses, channel messages, and email bodies, and citation syntax (`[[uuid]]`, `[[md;...]]`) works identically inside created documents. For linking to other Macro items from within that content, see the "Linking Macro items inside document content" rules. Non-Markdown documents (PDF, CSV, images, etc.) take raw content instead — no Markdown syntax or mention tags.
diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.md
index fd488c8167..9e3305f2c3 100644
--- a/docs/AGENT_GUIDE/ai-chat.md
+++ b/docs/AGENT_GUIDE/ai-chat.md
@@ -83,7 +83,8 @@ permission failures should display a failed tool call without a successful resul
`GenerateImage` takes a text prompt, renders it with Google's Nano Banana image
model, and saves the result to static file service. An optional aspect ratio
(`square`, `landscape`, `portrait`, `widescreen`, `tall`) controls its shape.
-The response includes `staticFileId` and the permanent image `url`; it does not
+The response includes `staticFileId`, the permanent image `url`, intrinsic pixel
+`width` and `height`, and ready-to-send `markdown`; it does not
create a document or take a filename or destination project.
For edits or variations, attach photos with the existing paperclip or use Macro
@@ -100,7 +101,14 @@ its SFS URL without a filename header or document navigation. It preserves its
aspect ratio and fits the available width. A status appears while generation is
pending; a failed image load shows “Preview unavailable”. The tool already renders
the result in chat, so the assistant should not add a document mention or duplicate
-image there. In channel messages, embed the returned URL as a Markdown image.
+image there. In channel messages, copy the returned `markdown` verbatim on its own line.
+Its `<m-image>` markup preserves dimensions and fits the image within 400 × 400
+pixels, so loading it does not change the channel row height. Do not replace it
+with a plain Markdown image URL, which loses the dimensions. Agent previews also
+reserve space from the returned dimensions, including on image-load failure.
+Historical results without dimensions retain their previous rendering.
+To verify, delay the image download and compare row bounds before and after load
+at desktop and narrow widths; repeat after reopening the conversation.
Earlier generations saved as DSS documents still render their original document
card when viewing historical conversations.
Refused prompts, provider failures, and hosts without a Google Generative AI key
diff --git a/packages/lexical-core/tests/generated-image.test.ts b/packages/lexical-core/tests/generated-image.test.ts
new file mode 100644
index 0000000000..f7df0dde40
--- /dev/null
+++ b/packages/lexical-core/tests/generated-image.test.ts
@@ -0,0 +1,60 @@
+import {
+ $convertFromMarkdownString,
+ $convertToMarkdownString,
+} from '@lexical/markdown';
+import { $nodesOfType, createEditor } from 'lexical';
+import { describe, expect, it } from 'vitest';
+import { SupportedNodeTypes } from '../node-list';
+import { ImageNode } from '../nodes/ImageNode';
+import { INTERNAL_TRANSFORMERS } from '../transformers';
+import { composeImageMarkdown } from '../utils/image-markdown';
+
+describe('generated channel images', () => {
+ it('retains dimensions through parsing and message editing before image download', () => {
+ const editor = createEditor({
+ nodes: SupportedNodeTypes,
+ onError: (error) => {
+ throw error;
+ },
+ });
+ const image = {
+ url: 'https://static.example/file/image',
+ srcType: 'sfs',
+ id: 'image',
+ alt: 'Generated image',
+ width: 1536,
+ height: 1024,
+ constrainedWidth: 400,
+ constrainedHeight: 400,
+ };
+ editor.update(
+ () => {
+ $convertFromMarkdownString(
+ composeImageMarkdown({
+ staticFileId: image.id,
+ url: image.url,
+ width: image.width,
+ height: image.height,
+ }),
+ INTERNAL_TRANSFORMERS
+ );
+ },
+ { discrete: true }
+ );
+ editor.getEditorState().read(() => {
+ const [node] = $nodesOfType(ImageNode);
+ expect(node).toBeDefined();
+ expect(node.getWidth()).toBe(1536);
+ expect(node.getHeight()).toBe(1024);
+ expect(node.getEffectiveDimensions()).toEqual({
+ width: 400,
+ height: 267,
+ });
+ const markdown = $convertToMarkdownString(INTERNAL_TRANSFORMERS);
+ const serialized = JSON.parse(
+ markdown.trim().slice('<m-image>'.length, -'</m-image>'.length)
+ );
+ expect(serialized).toMatchObject(image);
+ });
+ });
+});
diff --git a/packages/lexical-core/transformers/image.ts b/packages/lexical-core/transformers/image.ts
index afbb713981..a5511c0843 100644
--- a/packages/lexical-core/transformers/image.ts
+++ b/packages/lexical-core/transformers/image.ts
@@ -52,7 +52,7 @@ export const I_IMAGE_CONSTRAINED: ElementTransformer = {
constrainedWidth: data.constrainedWidth ?? undefined,
constrainedHeight: data.constrainedHeight ?? undefined,
});
- parent.append(imageNode);
+ parent.replace(imageNode);
} catch (e) {
console.error('Failed to parse m-image:', e);
replaceElementWithUnknownMention(parent, 'Unknown Image');
diff --git a/packages/lexical-core/utils/image-markdown.ts b/packages/lexical-core/utils/image-markdown.ts
new file mode 100644
index 0000000000..8989e26ef4
--- /dev/null
+++ b/packages/lexical-core/utils/image-markdown.ts
@@ -0,0 +1,40 @@
+import { createHeadlessEditor } from '@lexical/headless';
+import { $convertToMarkdownString } from '@lexical/markdown';
+import { $getRoot } from 'lexical';
+import { NodeReplacements, SupportedNodeTypes } from '../node-list';
+import { $createImageNode } from '../nodes/ImageNode';
+import { ALL_TRANSFORMERS } from '../transformers';
+
+export type ImageMarkdownInput = {
+ staticFileId: string;
+ url: string;
+ width: number;
+ height: number;
+};
+
+/** Compose channel image markup using the same node and serializer as the editor. */
+export function composeImageMarkdown(image: ImageMarkdownInput): string {
+ const editor = createHeadlessEditor({
+ nodes: [...SupportedNodeTypes, ...NodeReplacements],
+ });
+ editor.update(
+ () => {
+ $getRoot().append(
+ $createImageNode({
+ srcType: 'sfs',
+ id: image.staticFileId,
+ url: image.url,
+ alt: 'Generated image',
+ width: image.width,
+ height: image.height,
+ constrainedWidth: 400,
+ constrainedHeight: 400,
+ })
+ );
+ },
+ { discrete: true }
+ );
+ return editor
+ .getEditorState()
+ .read(() => $convertToMarkdownString(ALL_TRANSFORMERS));
+}
diff --git a/services/lexical-service/README.md b/services/lexical-service/README.md
index d16765458c..251ffef612 100644
--- a/services/lexical-service/README.md
+++ b/services/lexical-service/README.md
@@ -26,6 +26,13 @@ Returns the pre-processed document to be uses in the cognition service.
## POST /snapshot/markdown
Accepts `{ "markdown": "..." }` and returns an `application/octet-stream` Loro snapshot equivalent to the markdown block migration path.
+## POST /image-markdown
+Accepts `{ "staticFileId": "<uuid>", "url": "https://...", "width": 1536, "height": 1024 }`
+and returns `{ "markdown": "..." }` built from the shared Lexical image node.
+Requires internal authentication. Dimensions must be positive integers. The serialized
+image retains intrinsic dimensions and uses 400px channel attachment bounds.
+Deploy this endpoint before the image-generation backend that calls it.
+
# Local Development
`bun run dev` will start the development server with the wrangler env set to 'local' and the port set to 8931. The local
environment uses 'local' as the INTERNAL_API_SECRET_KEY. There are scripts to run document ids against the local endpoints.
diff --git a/services/lexical-service/src/endpoints/image-markdown.test.ts b/services/lexical-service/src/endpoints/image-markdown.test.ts
new file mode 100644
index 0000000000..4be2e89bc5
--- /dev/null
+++ b/services/lexical-service/src/endpoints/image-markdown.test.ts
@@ -0,0 +1,59 @@
+import '../polyfills/prism';
+import { describe, expect, it } from 'bun:test';
+import app from '../index';
+
+const image = {
+ staticFileId: '00112233-4455-4677-8899-aabbccddeeff',
+ url: 'https://static.example/file/image',
+ width: 1536,
+ height: 1024,
+};
+const request = (body: unknown, authenticated = true) =>
+ app.request(
+ '/image-markdown',
+ {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ ...(authenticated ? { 'x-internal-auth-key': 'test-key' } : {}),
+ },
+ body: JSON.stringify(body),
+ },
+ { INTERNAL_AUTH_KEY: 'test-key' }
+ );
+
+describe('image markdown endpoint', () => {
+ it('serializes a real image node with dimensions and channel constraints', async () => {
+ const response = await request(image);
+ expect(response.status).toBe(200);
+ const { markdown } = await response.json<{ markdown: string }>();
+ const data = JSON.parse(
+ markdown.slice('<m-image>'.length, -'</m-image>'.length)
+ );
+ expect(data).toEqual({
+ srcType: 'sfs',
+ id: image.staticFileId,
+ url: image.url,
+ alt: 'Generated image',
+ width: 1536,
+ height: 1024,
+ scale: 1,
+ constrainedWidth: 400,
+ constrainedHeight: 400,
+ });
+ });
+ it('requires internal authentication', async () => {
+ expect((await request(image, false)).status).toBe(401);
+ });
+ it.each([0, -1, 1.5, 4294967296])(
+ 'rejects invalid dimensions %s',
+ async (width) => {
+ expect((await request({ ...image, width })).status).toBe(400);
+ }
+ );
+ it('rejects malformed static file identifiers', async () => {
+ expect((await request({ ...image, staticFileId: 'invalid' })).status).toBe(
+ 400
+ );
+ });
+});
diff --git a/services/lexical-service/src/endpoints/image-markdown.ts b/services/lexical-service/src/endpoints/image-markdown.ts
new file mode 100644
index 0000000000..8c82063817
--- /dev/null
+++ b/services/lexical-service/src/endpoints/image-markdown.ts
@@ -0,0 +1,44 @@
+import { composeImageMarkdown } from '@macro-inc/lexical-core/utils/image-markdown';
+import { OpenAPIRoute } from 'chanfana';
+import type { Context } from 'hono';
+import { z } from 'zod';
+import { handleEndpointError } from '../lib/error-handler';
+import { standardErrorResponses } from '../lib/schemas';
+
+export class ImageMarkdownEndpoint extends OpenAPIRoute {
+ schema = {
+ summary: 'Compose channel image markdown with intrinsic dimensions',
+ request: {
+ body: {
+ content: {
+ 'application/json': {
+ schema: z.object({
+ staticFileId: z.string().uuid(),
+ url: z.string().url(),
+ width: z.number().int().positive().max(4294967295),
+ height: z.number().int().positive().max(4294967295),
+ }),
+ },
+ },
+ },
+ },
+ responses: {
+ 200: {
+ description: 'Image markdown serialized from a Lexical image node',
+ content: {
+ 'application/json': { schema: z.object({ markdown: z.string() }) },
+ },
+ },
+ ...standardErrorResponses,
+ },
+ };
+
+ async handle(c: Context) {
+ const { body } = await this.getValidatedData<typeof this.schema>();
+ try {
+ return c.json({ markdown: composeImageMarkdown(body) });
+ } catch (error) {
+ return handleEndpointError(error, c);
+ }
+ }
+}
diff --git a/services/lexical-service/src/index.ts b/services/lexical-service/src/index.ts
index b593715494..26470e08f9 100644
--- a/services/lexical-service/src/index.ts
+++ b/services/lexical-service/src/index.ts
@@ -10,6 +10,7 @@ import { CognitionV2Endpoint } from './endpoints/cognition-v2';
import { CommentMarkEndpoint } from './endpoints/comment-mark';
import { ExtractReplyEndpoint } from './endpoints/extract-reply';
import { HtmlEndpoint } from './endpoints/html';
+import { ImageMarkdownEndpoint } from './endpoints/image-markdown';
import { MarkdownEndpoint } from './endpoints/markdown';
import { MarkdownSnapshotEndpoint } from './endpoints/markdown-snapshot';
import { MentionsEndpoint } from './endpoints/mentions';
@@ -50,6 +51,7 @@ app.use('/mentions', internalAuth);
app.use('/extract-reply', internalAuth);
app.use('/agent-announcement', internalAuth);
app.use('/agent-context', internalAuth);
+app.use('/image-markdown', internalAuth);
app.use('/internal/health', internalAuth);
const openapi = fromHono(app, {
@@ -78,6 +80,7 @@ openapi.post('/mentions', MentionsEndpoint);
openapi.post('/extract-reply', ExtractReplyEndpoint);
openapi.post('/agent-announcement', AgentAnnouncementEndpoint);
openapi.post('/agent-context', AgentContextEndpoint);
+openapi.post('/image-markdown', ImageMarkdownEndpoint);
openapi.get('/internal/health', (c) => c.json({ status: 'healthy' }));
export default app;