@adecore/agents 0.18.3 → 0.19.0

package/dist/chat/visual-store.d.ts

@@ -1,4 +1,4 @@
-import { type ChatAttachment, type ChatVisual } from '@adecore/agent-contracts';
+import { type ChatAttachment, type ChatVisual, type VisualLayout } from '@adecore/agent-contracts';
 import type { AttachmentStore } from './attachment-store.ts';
 export declare function visualFileName(chatId: string): string;
 export declare function isVisualFileName(name: string): boolean;
@@ -6,6 +6,7 @@ export interface VisualInput {
     title: string;
     html: string;
     maxHeight?: number;
+    layout?: VisualLayout;
     heights?: ReadonlyArray<readonly [number, number]>;
     turnId?: string;
 }
@@ -23,12 +24,17 @@ export declare class VisualStore {
     constructor(home: string, attachments: AttachmentStore, options?: VisualStoreOptions);
     listen(listener: VisualListener): () => void;
     list(chatId: string): Promise<ChatVisual[]>;
+    workspacePath(chatId: string): string;
+    prepareWorkspace(chatId: string): Promise<string>;
+    writeSource(chatId: string, name: string, html: string): Promise<string>;
+    writePreview(chatId: string, png: Uint8Array): Promise<string>;
     publish(chatId: string, input: VisualInput): Promise<ChatVisual>;
     remove(chatId: string, visualId: string): Promise<ChatVisual[]>;
     removeChat(chatId: string): Promise<void>;
     copyChat(fromChatId: string, toChatId: string, keep?: (visual: ChatVisual) => boolean): Promise<ChatVisual[]>;
     attachment(chatId: string, visualId: string): ChatAttachment | null;
     pagePath(chatId: string, visualId: string): string;
+    private writeWorkspaceFile;
     private tell;
     private readFile;
     private writeFile;

package/dist/chat/visual-store.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { mkdir, readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ChatVisualsSchema, injectVisualBootstrap, VISUAL_LIMITS } from '@adecore/agent-contracts';
+import { ChatVisualsSchema, injectVisualBootstrap, VISUAL_LIMITS, VisualLayoutSchema } from '@adecore/agent-contracts';
 import { z } from 'zod';
 import { isNotFound, writeAtomic } from '../fs.js';
 import { KeyedSerializer } from '../serializer.js';
@@ -41,6 +41,9 @@ function checked(input) {
     if (!isSize(maxHeight) || maxHeight < VISUAL_LIMITS.minHeight || maxHeight > VISUAL_LIMITS.maxHeight) {
         refuse('visual-invalid', `The maximum height must be from ${VISUAL_LIMITS.minHeight} to ${VISUAL_LIMITS.maxHeight} CSS pixels; leave it out for ${VISUAL_LIMITS.maxHeight}`);
     }
+    if (input.layout !== undefined && !VisualLayoutSchema.safeParse(input.layout).success) {
+        refuse('visual-invalid', 'The layout must be inline or wide; leave it out for the reply column');
+    }
     const heights = input.heights ?? [];
     if (!Array.isArray(heights) ||
         heights.length > VISUAL_LIMITS.heights ||
@@ -50,7 +53,7 @@ function checked(input) {
     // One measurement per width, the last one given, ascending as `visualFrameHeight` reads them.
     const byWidth = new Map(heights.map((pair) => [Math.max(1, Math.round(pair[0])), Math.ceil(pair[1])]));
     const sorted = [...byWidth].sort((a, b) => a[0] - b[0]);
-    return { title, html: input.html, maxHeight: Math.round(maxHeight), heights: sorted.length === 0 ? undefined : sorted };
+    return { title, html: input.html, maxHeight: Math.round(maxHeight), layout: input.layout, heights: sorted.length === 0 ? undefined : sorted };
 }
 function tooLarge(bytes) {
     return refuse('visual-too-large', `The page is ${mebibytes(bytes)} and a visual may be at most ${mebibytes(VISUAL_LIMITS.bytes)}; ` +
@@ -85,9 +88,33 @@ export class VisualStore {
     list(chatId) {
         return this.writes.run(chatId, () => this.readFile(chatId));
     }
+    workspacePath(chatId) {
+        return join(this.dir, `${encodeURIComponent(chatId)}.visuals`);
+    }
+    async prepareWorkspace(chatId) {
+        const path = this.workspacePath(chatId);
+        await mkdir(path, { recursive: true, mode: 0o700 });
+        return path;
+    }
+    // Only a filename is accepted; an agent cannot make the host write outside its own chat.
+    async writeSource(chatId, name, html) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}\.html$/.test(name)) {
+            refuse('visual-invalid', 'Use an HTML filename such as chart.html, with letters, numbers, dots, hyphens or underscores and no directory');
+        }
+        if (html.trim() === '') {
+            refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
+        }
+        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
+            tooLarge(Buffer.byteLength(html, 'utf8'));
+        }
+        return this.writeWorkspaceFile(chatId, name, html);
+    }
+    writePreview(chatId, png) {
+        return this.writeWorkspaceFile(chatId, `preview-${randomBytes(8).toString('hex')}.png`, png);
+    }
     /* Stores a page with its bootstrap and adds it to the chat at the host's current time. */
     async publish(chatId, input) {
-        const { title, html, maxHeight, heights } = checked(input);
+        const { title, html, maxHeight, layout, heights } = checked(input);
         // Before the bootstrap is added, so a page far too large is never copied first.
         if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
             tooLarge(Buffer.byteLength(html, 'utf8'));
@@ -104,6 +131,7 @@ export class VisualStore {
                 title,
                 at: this.now(),
                 maxHeight,
+                ...(layout === undefined ? {} : { layout }),
                 ...(heights === undefined ? {} : { heights }),
                 size: page.byteLength,
                 ...(turnId === undefined ? {} : { turnId })
@@ -141,6 +169,7 @@ export class VisualStore {
         return this.writes.run(chatId, async () => {
             const visuals = await this.readFile(chatId).catch(() => null);
             await rm(join(this.dir, visualFileName(chatId)), { force: true });
+            await rm(this.workspacePath(chatId), { recursive: true, force: true });
             await Promise.all((visuals ?? []).map((visual) => rm(this.pagePath(chatId, visual.id), { force: true })));
             this.known.delete(chatId);
             if (visuals === null || visuals.length > 0) {
@@ -191,6 +220,13 @@ export class VisualStore {
     pagePath(chatId, visualId) {
         return join(this.attachments.folderOf(chatId), `${visualId}.html`);
     }
+    writeWorkspaceFile(chatId, name, content) {
+        return this.writes.run(chatId, async () => {
+            const path = join(await this.prepareWorkspace(chatId), name);
+            await writeAtomic(path, content);
+            return path;
+        });
+    }
     tell(chatId, visuals) {
         for (const listener of this.listeners) {
             listener(chatId, visuals);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.18.3",
+    "@adecore/agent-contracts": "0.19.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat/visual-store.ts

@@ -1,7 +1,16 @@
 import { randomBytes } from 'node:crypto';
 import { mkdir, readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ChatVisualsSchema, injectVisualBootstrap, VISUAL_LIMITS, type ChatAttachment, type ChatVisual, type VisualHeight } from '@adecore/agent-contracts';
+import {
+    ChatVisualsSchema,
+    injectVisualBootstrap,
+    VISUAL_LIMITS,
+    VisualLayoutSchema,
+    type ChatAttachment,
+    type ChatVisual,
+    type VisualHeight,
+    type VisualLayout
+} from '@adecore/agent-contracts';
 import { z } from 'zod';
 import { isNotFound, writeAtomic } from '../fs.ts';
 import { KeyedSerializer } from '../serializer.ts';
@@ -27,6 +36,7 @@ export interface VisualInput {
     html: string;
     // CSS pixels; absent, the largest a frame may be.
     maxHeight?: number;
+    layout?: VisualLayout;
     // `[width, height]` in CSS pixels, from a host that measured the page before publishing it.
     heights?: ReadonlyArray<readonly [number, number]>;
     turnId?: string;
@@ -54,7 +64,13 @@ function isSize(value: unknown): value is number {
 }
 
 /* The input as it is kept, or a refusal that tells the agent what to change. */
-function checked(input: VisualInput): { title: string; html: string; maxHeight: number; heights: VisualHeight[] | undefined } {
+function checked(input: VisualInput): {
+    title: string;
+    html: string;
+    maxHeight: number;
+    layout: VisualLayout | undefined;
+    heights: VisualHeight[] | undefined;
+} {
     const title = typeof input.title === 'string' ? input.title.trim() : '';
     if (title === '') {
         refuse('visual-invalid', 'A visual needs a title; give it a short one that says what the page shows');
@@ -72,6 +88,9 @@ function checked(input: VisualInput): { title: string; html: string; maxHeight:
             `The maximum height must be from ${VISUAL_LIMITS.minHeight} to ${VISUAL_LIMITS.maxHeight} CSS pixels; leave it out for ${VISUAL_LIMITS.maxHeight}`
         );
     }
+    if (input.layout !== undefined && !VisualLayoutSchema.safeParse(input.layout).success) {
+        refuse('visual-invalid', 'The layout must be inline or wide; leave it out for the reply column');
+    }
     const heights = input.heights ?? [];
     if (
         !Array.isArray(heights) ||
@@ -83,7 +102,7 @@ function checked(input: VisualInput): { title: string; html: string; maxHeight:
     // One measurement per width, the last one given, ascending as `visualFrameHeight` reads them.
     const byWidth = new Map(heights.map((pair): [number, number] => [Math.max(1, Math.round(pair[0])), Math.ceil(pair[1])]));
     const sorted = [...byWidth].sort((a, b) => a[0] - b[0]);
-    return { title, html: input.html, maxHeight: Math.round(maxHeight), heights: sorted.length === 0 ? undefined : sorted };
+    return { title, html: input.html, maxHeight: Math.round(maxHeight), layout: input.layout, heights: sorted.length === 0 ? undefined : sorted };
 }
 
 function tooLarge(bytes: number): never {
@@ -127,9 +146,37 @@ export class VisualStore {
         return this.writes.run(chatId, () => this.readFile(chatId));
     }
 
+    workspacePath(chatId: string): string {
+        return join(this.dir, `${encodeURIComponent(chatId)}.visuals`);
+    }
+
+    async prepareWorkspace(chatId: string): Promise<string> {
+        const path = this.workspacePath(chatId);
+        await mkdir(path, { recursive: true, mode: 0o700 });
+        return path;
+    }
+
+    // Only a filename is accepted; an agent cannot make the host write outside its own chat.
+    async writeSource(chatId: string, name: string, html: string): Promise<string> {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}\.html$/.test(name)) {
+            refuse('visual-invalid', 'Use an HTML filename such as chart.html, with letters, numbers, dots, hyphens or underscores and no directory');
+        }
+        if (html.trim() === '') {
+            refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
+        }
+        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
+            tooLarge(Buffer.byteLength(html, 'utf8'));
+        }
+        return this.writeWorkspaceFile(chatId, name, html);
+    }
+
+    writePreview(chatId: string, png: Uint8Array): Promise<string> {
+        return this.writeWorkspaceFile(chatId, `preview-${randomBytes(8).toString('hex')}.png`, png);
+    }
+
     /* Stores a page with its bootstrap and adds it to the chat at the host's current time. */
     async publish(chatId: string, input: VisualInput): Promise<ChatVisual> {
-        const { title, html, maxHeight, heights } = checked(input);
+        const { title, html, maxHeight, layout, heights } = checked(input);
         // Before the bootstrap is added, so a page far too large is never copied first.
         if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
             tooLarge(Buffer.byteLength(html, 'utf8'));
@@ -146,6 +193,7 @@ export class VisualStore {
                 title,
                 at: this.now(),
                 maxHeight,
+                ...(layout === undefined ? {} : { layout }),
                 ...(heights === undefined ? {} : { heights }),
                 size: page.byteLength,
                 ...(turnId === undefined ? {} : { turnId })
@@ -184,6 +232,7 @@ export class VisualStore {
         return this.writes.run(chatId, async () => {
             const visuals = await this.readFile(chatId).catch(() => null);
             await rm(join(this.dir, visualFileName(chatId)), { force: true });
+            await rm(this.workspacePath(chatId), { recursive: true, force: true });
             await Promise.all((visuals ?? []).map((visual) => rm(this.pagePath(chatId, visual.id), { force: true })));
             this.known.delete(chatId);
             if (visuals === null || visuals.length > 0) {
@@ -238,6 +287,14 @@ export class VisualStore {
         return join(this.attachments.folderOf(chatId), `${visualId}.html`);
     }
 
+    private writeWorkspaceFile(chatId: string, name: string, content: string | Uint8Array): Promise<string> {
+        return this.writes.run(chatId, async () => {
+            const path = join(await this.prepareWorkspace(chatId), name);
+            await writeAtomic(path, content);
+            return path;
+        });
+    }
+
     private tell(chatId: string, visuals: ChatVisual[]): void {
         for (const listener of this.listeners) {
             listener(chatId, visuals);