@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/services/virtual-filesystem.js

@@ -0,0 +1,410 @@
+import crypto from "node:crypto";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { writeJsonAtomic } from "../utils/atomic-json.js";
+const DEFAULT_QUOTA_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
+export class VirtualFilesystemError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "VirtualFilesystemError";
+    }
+}
+export class VirtualFilesystemService {
+    projectId;
+    projectRoot;
+    filesRoot;
+    snapshotsRoot;
+    quotaBytes;
+    maxFileBytes;
+    now;
+    constructor(options) {
+        this.projectId = sanitizeProjectId(options.projectId);
+        const stateDir = options.stateDir ?? resolveStateDir(process.env, os.homedir);
+        this.projectRoot = path.join(stateDir, "agent-vfs", "projects", this.projectId);
+        this.filesRoot = path.join(this.projectRoot, "files");
+        this.snapshotsRoot = path.join(this.projectRoot, "snapshots");
+        this.quotaBytes = options.quotaBytes ?? DEFAULT_QUOTA_BYTES;
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        this.now = options.now ?? (() => new Date());
+    }
+    async initialize() {
+        await fsp.mkdir(this.filesRoot, { recursive: true, mode: 0o700 });
+        await fsp.mkdir(this.snapshotsRoot, { recursive: true, mode: 0o700 });
+    }
+    async writeFile(virtualPath, contents) {
+        const data = typeof contents === "string"
+            ? Buffer.from(contents)
+            : Buffer.from(contents);
+        if (data.byteLength > this.maxFileBytes) {
+            throw new VirtualFilesystemError(`File exceeds max file size of ${this.maxFileBytes} bytes`, "QUOTA_EXCEEDED");
+        }
+        const target = this.resolvePath(virtualPath);
+        await this.ensureSafeParentDirectory(target);
+        await this.rejectSymlinkIfExists(target);
+        const existingSize = await this.fileSizeIfExists(target);
+        const current = await this.measureFiles();
+        const nextBytes = current.bytes - existingSize + data.byteLength;
+        if (nextBytes > this.quotaBytes) {
+            throw new VirtualFilesystemError(`Project quota exceeded: ${nextBytes}/${this.quotaBytes} bytes`, "QUOTA_EXCEEDED");
+        }
+        await fsp.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        await fsp.writeFile(target, data, { mode: 0o600 });
+        return this.entryFor(target);
+    }
+    async readFile(virtualPath, encoding = "utf-8") {
+        const target = this.resolvePath(virtualPath);
+        await this.assertFile(target);
+        return fsp.readFile(target, encoding);
+    }
+    async readFileBytes(virtualPath) {
+        const target = this.resolvePath(virtualPath);
+        await this.assertFile(target);
+        return fsp.readFile(target);
+    }
+    async list(virtualPath = ".", options = {}) {
+        const target = this.resolvePath(virtualPath);
+        await this.assertDirectory(target);
+        const entries = await this.listEntries(target, Boolean(options.recursive));
+        return entries.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async delete(virtualPath, options = {}) {
+        const target = this.resolvePath(virtualPath);
+        await this.ensureSafeParentDirectory(target);
+        await this.rejectSymlinkIfExists(target);
+        await fsp.rm(target, {
+            recursive: Boolean(options.recursive),
+            force: false,
+        });
+    }
+    async createSnapshot(note) {
+        await this.initialize();
+        const id = snapshotId(this.now());
+        const snapshotDir = path.join(this.snapshotsRoot, id);
+        const snapshotFilesRoot = path.join(snapshotDir, "files");
+        await fsp.mkdir(snapshotFilesRoot, { recursive: true, mode: 0o700 });
+        await fsp.cp(this.filesRoot, snapshotFilesRoot, {
+            recursive: true,
+            errorOnExist: false,
+            force: true,
+            dereference: false,
+        });
+        const stats = await this.measureTree(snapshotFilesRoot);
+        const snapshot = {
+            id,
+            projectId: this.projectId,
+            createdAt: this.now().toISOString(),
+            root: snapshotFilesRoot,
+            filesBytes: stats.bytes,
+            fileCount: stats.fileCount,
+            ...(note ? { note } : {}),
+        };
+        await writeJsonAtomic(path.join(snapshotDir, "snapshot.json"), snapshot);
+        return snapshot;
+    }
+    async getSnapshot(id) {
+        const snapshot = await this.readSnapshot(id);
+        if (!snapshot) {
+            throw new VirtualFilesystemError(`Snapshot not found: ${id}`, "SNAPSHOT_NOT_FOUND");
+        }
+        return snapshot;
+    }
+    async diffSnapshots(beforeSnapshotId, afterSnapshotId) {
+        const before = await this.snapshotFilesRoot(beforeSnapshotId);
+        const after = await this.snapshotFilesRoot(afterSnapshotId);
+        const beforeIndex = await this.indexTree(before);
+        const afterIndex = await this.indexTree(after);
+        return diffIndexes(beforeIndex, afterIndex);
+    }
+    async diffCurrent(snapshotId) {
+        const before = await this.snapshotFilesRoot(snapshotId);
+        const beforeIndex = await this.indexTree(before);
+        const afterIndex = await this.indexTree(this.filesRoot);
+        return diffIndexes(beforeIndex, afterIndex);
+    }
+    async rollback(snapshotId) {
+        const snapshotRoot = await this.snapshotFilesRoot(snapshotId);
+        const previous = await this.createSnapshot(`pre-rollback:${snapshotId}`);
+        await fsp.rm(this.filesRoot, { recursive: true, force: true });
+        await fsp.mkdir(this.filesRoot, { recursive: true, mode: 0o700 });
+        await fsp.cp(snapshotRoot, this.filesRoot, {
+            recursive: true,
+            errorOnExist: false,
+            force: true,
+            dereference: false,
+        });
+        const rollback = {
+            snapshotId,
+            projectId: this.projectId,
+            rolledBackAt: this.now().toISOString(),
+            previousSnapshotId: previous.id,
+        };
+        await writeJsonAtomic(path.join(this.projectRoot, "last-rollback.json"), rollback);
+        return rollback;
+    }
+    resolveVirtualPath(virtualPath) {
+        return toVirtualPath(this.resolvePath(virtualPath), this.filesRoot);
+    }
+    /**
+     * Resolve a virtual path to its absolute on-disk location, applying the same
+     * traversal/symlink rules used by readFile/writeFile. The returned path is
+     * always inside the project's `filesRoot` and is the path Node/Bun will use
+     * if you `pathToFileURL()` it for a dynamic import. The path is not required
+     * to exist — callers that need existence should `readFile` it first.
+     */
+    resolveDiskPath(virtualPath) {
+        return this.resolvePath(virtualPath);
+    }
+    resolvePath(virtualPath) {
+        const normalized = normalizeVirtualPath(virtualPath);
+        const resolved = path.resolve(this.filesRoot, normalized);
+        if (!isWithin(this.filesRoot, resolved)) {
+            throw new VirtualFilesystemError("Path escapes virtual filesystem root", "PATH_TRAVERSAL");
+        }
+        return resolved;
+    }
+    async ensureSafeParentDirectory(target) {
+        const relativeParent = path.relative(this.filesRoot, path.dirname(target));
+        if (!relativeParent)
+            return;
+        let current = this.filesRoot;
+        for (const segment of relativeParent.split(path.sep)) {
+            current = path.join(current, segment);
+            const stat = await lstatOrNull(current);
+            if (!stat)
+                continue;
+            if (stat.isSymbolicLink()) {
+                throw new VirtualFilesystemError(`Symlink path component denied: ${toVirtualPath(current, this.filesRoot)}`, "SYMLINK_DENIED");
+            }
+            if (!stat.isDirectory()) {
+                throw new VirtualFilesystemError("Parent path is not a directory", "NOT_DIRECTORY");
+            }
+        }
+    }
+    async rejectSymlinkIfExists(target) {
+        const stat = await lstatOrNull(target);
+        if (stat?.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+    }
+    async assertFile(target) {
+        await this.ensureSafeParentDirectory(target);
+        const stat = await lstatOrNull(target);
+        if (!stat) {
+            throw new VirtualFilesystemError("File not found", "NOT_FOUND");
+        }
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isFile()) {
+            throw new VirtualFilesystemError("Path is not a file", "NOT_FILE");
+        }
+    }
+    async assertDirectory(target) {
+        await this.ensureSafeParentDirectory(target);
+        const stat = await lstatOrNull(target);
+        if (!stat) {
+            throw new VirtualFilesystemError("Directory not found", "NOT_FOUND");
+        }
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isDirectory()) {
+            throw new VirtualFilesystemError("Path is not a directory", "NOT_DIRECTORY");
+        }
+    }
+    async entryFor(realPath) {
+        const stat = await fsp.lstat(realPath);
+        return {
+            path: toVirtualPath(realPath, this.filesRoot),
+            type: stat.isDirectory() ? "directory" : "file",
+            size: stat.isFile() ? stat.size : 0,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    async listEntries(realDir, recursive) {
+        const dirents = await fsp.readdir(realDir, { withFileTypes: true });
+        const entries = [];
+        for (const dirent of dirents) {
+            const realPath = path.join(realDir, dirent.name);
+            if (dirent.isSymbolicLink()) {
+                throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+            }
+            const entry = await this.entryFor(realPath);
+            entries.push(entry);
+            if (recursive && dirent.isDirectory()) {
+                entries.push(...(await this.listEntries(realPath, true)));
+            }
+        }
+        return entries;
+    }
+    async measureFiles() {
+        return this.measureTree(this.filesRoot);
+    }
+    async measureTree(root) {
+        const stat = await lstatOrNull(root);
+        if (!stat)
+            return { bytes: 0, fileCount: 0 };
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (stat.isFile()) {
+            return { bytes: stat.size, fileCount: 1 };
+        }
+        if (!stat.isDirectory()) {
+            return { bytes: 0, fileCount: 0 };
+        }
+        let bytes = 0;
+        let fileCount = 0;
+        for (const entry of await fsp.readdir(root, { withFileTypes: true })) {
+            const child = path.join(root, entry.name);
+            const stats = await this.measureTree(child);
+            bytes += stats.bytes;
+            fileCount += stats.fileCount;
+        }
+        return { bytes, fileCount };
+    }
+    async fileSizeIfExists(realPath) {
+        const stat = await lstatOrNull(realPath);
+        if (!stat)
+            return 0;
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isFile()) {
+            throw new VirtualFilesystemError("Path is not a file", "NOT_FILE");
+        }
+        return stat.size;
+    }
+    async readSnapshot(id) {
+        const normalizedId = normalizeSnapshotId(id);
+        const metadataPath = path.join(this.snapshotsRoot, normalizedId, "snapshot.json");
+        const raw = await fsp.readFile(metadataPath, "utf-8").catch(() => null);
+        return raw ? JSON.parse(raw) : null;
+    }
+    async snapshotFilesRoot(id) {
+        const snapshot = await this.getSnapshot(id);
+        const root = path.join(this.snapshotsRoot, normalizeSnapshotId(snapshot.id), "files");
+        if (!isWithin(this.snapshotsRoot, root)) {
+            throw new VirtualFilesystemError("Snapshot path escapes snapshot root", "PATH_TRAVERSAL");
+        }
+        return root;
+    }
+    async indexTree(root) {
+        const index = new Map();
+        const walk = async (dir) => {
+            for (const dirent of await fsp.readdir(dir, { withFileTypes: true })) {
+                const realPath = path.join(dir, dirent.name);
+                if (dirent.isSymbolicLink()) {
+                    throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+                }
+                const stat = await fsp.lstat(realPath);
+                const entry = {
+                    path: toVirtualPath(realPath, root),
+                    type: stat.isDirectory() ? "directory" : "file",
+                    size: stat.isFile() ? stat.size : 0,
+                    mtimeMs: stat.mtimeMs,
+                    ...(stat.isFile() ? { hash: await sha256(realPath) } : {}),
+                };
+                index.set(entry.path, entry);
+                if (dirent.isDirectory()) {
+                    await walk(realPath);
+                }
+            }
+        };
+        await walk(root);
+        return index;
+    }
+}
+export function createVirtualFilesystemService(options) {
+    return new VirtualFilesystemService(options);
+}
+function sanitizeProjectId(projectId) {
+    const sanitized = projectId.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
+    if (!sanitized || sanitized === "." || sanitized === "..") {
+        throw new VirtualFilesystemError("Invalid VFS project id", "INVALID_PATH");
+    }
+    return sanitized.slice(0, 120);
+}
+function normalizeVirtualPath(input) {
+    if (typeof input !== "string" || input.includes("\0")) {
+        throw new VirtualFilesystemError("Invalid virtual path", "INVALID_PATH");
+    }
+    const value = input.trim().replace(/\\/g, "/");
+    if (!value || value === "." || value === "/") {
+        return ".";
+    }
+    const segments = value.split("/").filter(Boolean);
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new VirtualFilesystemError("Path traversal segments are not allowed", "PATH_TRAVERSAL");
+    }
+    return segments.join(path.sep);
+}
+function normalizeSnapshotId(id) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(id)) {
+        throw new VirtualFilesystemError("Invalid snapshot id", "INVALID_PATH");
+    }
+    return id;
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function toVirtualPath(realPath, root) {
+    const relative = path.relative(root, realPath).replace(/\\/g, "/");
+    return relative ? `/${relative}` : "/";
+}
+async function lstatOrNull(realPath) {
+    try {
+        return await fsp.lstat(realPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function snapshotId(now) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    return `${stamp}-${crypto.randomBytes(4).toString("hex")}`;
+}
+async function sha256(realPath) {
+    const hash = crypto.createHash("sha256");
+    hash.update(await fsp.readFile(realPath));
+    return hash.digest("hex");
+}
+function diffIndexes(before, after) {
+    const paths = new Set([...before.keys(), ...after.keys()]);
+    const diff = [];
+    for (const entryPath of [...paths].sort()) {
+        const beforeEntry = before.get(entryPath);
+        const afterEntry = after.get(entryPath);
+        if (!beforeEntry && afterEntry) {
+            diff.push({ path: entryPath, status: "added", after: afterEntry });
+            continue;
+        }
+        if (beforeEntry && !afterEntry) {
+            diff.push({ path: entryPath, status: "deleted", before: beforeEntry });
+            continue;
+        }
+        if (!beforeEntry || !afterEntry)
+            continue;
+        const same = beforeEntry.type === afterEntry.type &&
+            beforeEntry.size === afterEntry.size &&
+            beforeEntry.hash === afterEntry.hash;
+        if (!same) {
+            diff.push({
+                path: entryPath,
+                status: "modified",
+                before: beforeEntry,
+                after: afterEntry,
+            });
+        }
+    }
+    return diff;
+}

package/dist/packages/agent/src/shared/conversation-format.d.ts

@@ -0,0 +1,11 @@
+import type { IAgentRuntime, Memory, Room } from "@elizaos/core";
+export declare function formatSpeakerLabel(runtime: IAgentRuntime, memory: Memory): string;
+/**
+ * Format a Room into a "[source] name" tag for display in provider output.
+ */
+export declare function roomSourceTag(room: Room | null): string;
+/**
+ * Format a createdAt timestamp as a human-readable relative string.
+ */
+export declare function formatRelativeTimestamp(createdAt?: number): string;
+//# sourceMappingURL=conversation-format.d.ts.map

package/dist/packages/agent/src/shared/conversation-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-format.d.ts","sourceRoot":"","sources":["../../../../../src/shared/conversation-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AA2BjE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAYlE"}

package/dist/packages/agent/src/shared/conversation-format.js

@@ -0,0 +1,69 @@
+import { asNonEmptyString, asRecord } from "@elizaos/shared";
+const readString = asNonEmptyString;
+function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+function formatExternalSpeakerLabel(displayName, userName, source) {
+    if (displayName &&
+        userName &&
+        normalizeName(displayName) !== normalizeName(userName)) {
+        if (source === "discord") {
+            return `${displayName} (discord username: ${userName})`;
+        }
+        return `${displayName} (username: ${userName})`;
+    }
+    return displayName ?? userName ?? "user";
+}
+export function formatSpeakerLabel(runtime, memory) {
+    if (memory.entityId === runtime.agentId) {
+        return runtime.character?.name ?? "agent";
+    }
+    const metadata = asRecord(memory.metadata);
+    const content = asRecord(memory.content);
+    const defaultMetadata = asRecord(metadata?.default);
+    const source = readString(content?.source);
+    const sourceMetadata = source ? asRecord(metadata?.[source]) : null;
+    const displayName = readString(metadata?.entityName) ??
+        readString(metadata?.displayName) ??
+        readString(sourceMetadata?.displayName) ??
+        readString(sourceMetadata?.name) ??
+        readString(defaultMetadata?.name) ??
+        readString(metadata?.name);
+    const userName = readString(metadata?.entityUserName) ??
+        readString(sourceMetadata?.userName) ??
+        readString(sourceMetadata?.username) ??
+        readString(defaultMetadata?.username) ??
+        readString(metadata?.userName) ??
+        readString(metadata?.username);
+    return formatExternalSpeakerLabel(displayName, userName, source);
+}
+/**
+ * Format a Room into a "[source] name" tag for display in provider output.
+ */
+export function roomSourceTag(room) {
+    if (!room)
+        return "[unknown]";
+    const source = room.source || (room.type ?? "chat");
+    const name = room.name || room.id?.slice(0, 8);
+    return `[${source}] ${name}`;
+}
+/**
+ * Format a createdAt timestamp as a human-readable relative string.
+ */
+export function formatRelativeTimestamp(createdAt) {
+    if (!createdAt)
+        return "";
+    const date = new Date(createdAt);
+    const now = Date.now();
+    const diffMs = now - date.getTime();
+    if (diffMs < 60_000)
+        return "just now";
+    const minutes = Math.floor(diffMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}

package/dist/packages/agent/src/shared/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./conversation-format.ts";
+export * from "./ui-catalog-prompt.ts";
+export * from "./workspace-resolution.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/agent/src/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC"}

package/dist/packages/agent/src/shared/index.js

@@ -0,0 +1,3 @@
+export * from "./conversation-format.js";
+export * from "./ui-catalog-prompt.js";
+export * from "./workspace-resolution.js";

package/dist/packages/agent/src/shared/ui-catalog-prompt.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ui-catalog-prompt.ts -- Static instruction prompt + dynamic component
+ * catalog used by LLMs to emit valid UiSpec JSON-patch output.
+ *
+ * The instruction prompt and the catalog are separate so callers can
+ * include only what they need (e.g. only form components, or only the
+ * patch format with no examples).
+ *
+ * Exports:
+ *   - COMPONENT_CATALOG, ComponentMeta, getComponentNames — catalog data
+ *   - UI_INSTRUCTION_HEADER_GENERATE / UI_INSTRUCTION_HEADER_CHAT —
+ *       mode-specific opening sentence
+ *   - UI_PATCH_FORMAT — patch format + path conventions + element schema
+ *   - UI_BINDING_DOCS — data binding, state, visibility, validation,
+ *       events, and repeat (composed from smaller named blocks)
+ *   - UI_EXAMPLE_GENERATE / UI_EXAMPLE_CHAT — one canonical example each
+ *   - formatComponentCatalogForPrompt(options?) — renders the catalog
+ *   - generateCatalogPrompt(options?) — back-compat assembler
+ */
+interface PropMeta {
+    type: string;
+    description: string;
+    required?: boolean;
+}
+export interface ComponentMeta {
+    description: string;
+    props: Record<string, PropMeta>;
+    slots?: string[];
+}
+export declare const COMPONENT_CATALOG: Record<string, ComponentMeta>;
+/** Returns the list of all component type names in the catalog. */
+export declare function getComponentNames(): string[];
+export interface FormatComponentCatalogOptions {
+    /** Render only these component types. Names not in the catalog are ignored. */
+    include?: string[];
+    /** Override the section heading. Defaults to "## Available components". */
+    heading?: string;
+}
+/**
+ * Renders the component catalog as a Markdown section suitable for
+ * embedding in a system prompt. Pass `include` to render a subset.
+ */
+export declare function formatComponentCatalogForPrompt(options?: FormatComponentCatalogOptions): string;
+/** Opening sentence for "generate" mode (JSONL-only output). */
+export declare const UI_INSTRUCTION_HEADER_GENERATE = "You are generating UI specifications as JSONL patches. Output ONLY the patches \u2014 one JSON object per line, no prose, no markdown, no code fences.";
+/** Opening sentences for "chat" mode (prose + inline JSONL when useful). */
+export declare const UI_INSTRUCTION_HEADER_CHAT = "You can generate interactive UI components inline in your responses using JSONL patches.\n\nWhen the user's request calls for a form, chart, slider, metric display, wallet control, or any interactive element, respond conversationally first (one or two sentences), then emit the JSONL patches on their own lines immediately after. Each patch must be on its own line with no extra whitespace or code fences.\n\nWhen no UI is needed (greetings, factual questions, clarifications) \u2014 reply with text only. Never emit patches unless they genuinely add value.";
+/** Patch wire format: ops, paths, element schema, ordering rules. */
+export declare const UI_PATCH_FORMAT = "## Output format \u2014 JSONL patches (RFC 6902)\n\nEach line of UI output is a single JSON patch operation:\n\n```\n{\"op\":\"add\",\"path\":\"/root\",\"value\":\"card-1\"}\n{\"op\":\"add\",\"path\":\"/elements/card-1\",\"value\":{\"type\":\"Card\",\"props\":{\"title\":\"My Form\"},\"children\":[\"input-1\",\"btn-1\"]}}\n{\"op\":\"add\",\"path\":\"/elements/input-1\",\"value\":{\"type\":\"Input\",\"props\":{\"label\":\"Amount\",\"type\":\"number\",\"statePath\":\"amount\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/elements/btn-1\",\"value\":{\"type\":\"Button\",\"props\":{\"label\":\"Submit\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/state/amount\",\"value\":0}\n```\n\n**Path conventions:**\n- `/root` \u2014 set the root element ID (required, must be first)\n- `/elements/<id>` \u2014 add/replace an element\n- `/state/<key>` \u2014 set initial state value\n- `/state` \u2014 set the entire state object at once\n\n**Element schema:**\n```\n{\n  \"type\": \"<ComponentType>\",\n  \"props\": { ... },\n  \"children\": [\"child-id-1\", \"child-id-2\"],\n  \"on\": { ... },          // optional event bindings\n  \"visible\": { ... },     // optional visibility condition\n  \"validation\": { ... },  // optional validation\n  \"repeat\": { ... }       // optional list rendering\n}\n```\n\nAlways emit `/root` first, then all `/elements` entries, then `/state` values.\nElement IDs must be unique kebab-case strings (e.g. `send-btn`, `amount-slider`).";
+/** Data binding section. */
+export declare const UI_DATA_BINDING = "## Data binding\n\nReference state values dynamically in props using either syntax:\n\n1. **String prefix**: `\"$data.path.to.value\"` -- the value at that state path is resolved at render time.\n2. **Object syntax**: `{ \"$path\": \"path.to.value\" }` -- equivalent, useful when the value is not a string.\n\nInside a `repeat` block, reference the current item's fields with `\"$data.$item/fieldName\"` or `{ \"$path\": \"$item/fieldName\" }`.";
+/** State binding section. */
+export declare const UI_STATE_BINDING = "## State binding\n\nForm elements accept a `statePath` prop (dot-delimited path into `state`). This creates two-way binding: the element reads its current value from the path and writes back on user input. Example: `\"statePath\": \"form.email\"` binds to `state.form.email`.";
+/** Visibility section. */
+export declare const UI_VISIBILITY = "## Visibility\n\nAny element can have a `visible` condition. If it evaluates to false, the element is not rendered.\n\n**Path-based condition:**\n```\n{ \"path\": \"form.role\", \"operator\": \"eq\", \"value\": \"admin\" }\n```\nOperators: eq, ne, gt, gte, lt, lte.\n\n**Auth-based condition:**\n```\n{ \"auth\": \"signedIn\" }\n```\nValues: signedIn, signedOut, admin, or any custom role string.\n\n**Logical combinators:**\n```\n{ \"and\": [ <condition>, <condition> ] }\n{ \"or\": [ <condition>, <condition> ] }\n{ \"not\": <condition> }\n```";
+/** Validation section. */
+export declare const UI_VALIDATION = "## Validation\n\nForm elements can declare a `validation` object:\n\n```\n{\n  \"checks\": [\n    { \"fn\": \"required\", \"message\": \"This field is required\" },\n    { \"fn\": \"email\", \"message\": \"Enter a valid email\" },\n    { \"fn\": \"minLength\", \"args\": { \"length\": 3 }, \"message\": \"At least 3 characters\" }\n  ],\n  \"validateOn\": \"blur\"\n}\n```\n\n`validateOn`: \"change\" | \"blur\" | \"submit\" (defaults to submit).\n\nBuilt-in validators:\n- **required** -- value must not be null or empty string\n- **email** -- must match email pattern\n- **minLength** -- args: { length: number }\n- **maxLength** -- args: { length: number }\n- **pattern** -- args: { pattern: string } (regex)\n- **min** -- args: { value: number }\n- **max** -- args: { value: number }";
+/** Events section. */
+export declare const UI_EVENTS = "## Events\n\nElements can have an `on` property mapping event names to actions:\n\n```\n{\n  \"on\": {\n    \"press\": {\n      \"action\": \"submitForm\",\n      \"params\": { \"formId\": \"contactForm\" },\n      \"confirm\": {\n        \"title\": \"Confirm submission\",\n        \"message\": \"Are you sure?\",\n        \"confirmLabel\": \"Yes\",\n        \"cancelLabel\": \"No\"\n      },\n      \"onSuccess\": { \"action\": \"showToast\", \"params\": { \"message\": \"Saved!\" } },\n      \"onError\": { \"action\": \"showToast\", \"params\": { \"message\": \"Failed.\" } }\n    }\n  }\n}\n```\n\nCommon event names: press, change. The `action` string identifies the handler. `params`, `confirm`, `onSuccess`, and `onError` are all optional.";
+/** Repeat / list rendering section. */
+export declare const UI_REPEAT = "## Repeat / list rendering\n\nRender an element once per item in a state array:\n\n```\n{\n  \"type\": \"Card\",\n  \"props\": { \"title\": \"$data.$item/name\" },\n  \"children\": [],\n  \"repeat\": { \"path\": \"users\", \"key\": \"id\" }\n}\n```\n\n- `path`: dot-path to an array in state.\n- `key`: field name on each item used as the unique key.\n- Inside the repeated element and its children, use `$data.$item/fieldName` or `{ \"$path\": \"$item/fieldName\" }` to reference item fields.";
+/**
+ * All binding-related docs (data, state, visibility, validation, events,
+ * repeat) joined for convenience. Callers that only need a subset can
+ * import the individual blocks.
+ */
+export declare const UI_BINDING_DOCS: string;
+/** Canonical example for "generate" mode. */
+export declare const UI_EXAMPLE_GENERATE = "## Example \u2014 generate mode\n\n```\n{\"op\":\"add\",\"path\":\"/root\",\"value\":\"main\"}\n{\"op\":\"add\",\"path\":\"/elements/main\",\"value\":{\"type\":\"Card\",\"props\":{\"title\":\"Contact Us\"},\"children\":[\"heading\",\"desc\",\"email-input\",\"submit-btn\"]}}\n{\"op\":\"add\",\"path\":\"/elements/heading\",\"value\":{\"type\":\"Heading\",\"props\":{\"text\":\"Get in Touch\",\"level\":\"h2\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/elements/desc\",\"value\":{\"type\":\"Text\",\"props\":{\"text\":\"Fill out the form and we will respond within 24 hours.\",\"variant\":\"muted\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/elements/email-input\",\"value\":{\"type\":\"Input\",\"props\":{\"label\":\"Email\",\"type\":\"email\",\"placeholder\":\"you@example.com\",\"statePath\":\"form.email\"},\"children\":[],\"validation\":{\"checks\":[{\"fn\":\"required\",\"message\":\"Email is required\"},{\"fn\":\"email\",\"message\":\"Enter a valid email\"}],\"validateOn\":\"blur\"}}}\n{\"op\":\"add\",\"path\":\"/elements/submit-btn\",\"value\":{\"type\":\"Button\",\"props\":{\"label\":\"Send Message\",\"variant\":\"primary\"},\"children\":[],\"on\":{\"press\":{\"action\":\"submitContact\",\"params\":{\"email\":{\"$path\":\"form.email\"}}}}}}\n{\"op\":\"add\",\"path\":\"/state/form\",\"value\":{\"email\":\"\"}}\n```";
+/** Canonical example for "chat" mode (prose + JSONL + a text-only reply). */
+export declare const UI_EXAMPLE_CHAT = "## Example \u2014 chat mode\n\nUser: \"Help me send some BNB to a friend\"\n\nYour response:\n\n```\nSure! Here's a quick send form \u2014 enter the amount and recipient address:\n\n{\"op\":\"add\",\"path\":\"/root\",\"value\":\"send-card\"}\n{\"op\":\"add\",\"path\":\"/elements/send-card\",\"value\":{\"type\":\"Card\",\"props\":{\"title\":\"Send BNB\"},\"children\":[\"amount-slider\",\"amount-display\",\"addr-input\",\"send-btn\"]}}\n{\"op\":\"add\",\"path\":\"/elements/amount-slider\",\"value\":{\"type\":\"Slider\",\"props\":{\"label\":\"Amount (BNB)\",\"min\":0,\"max\":10,\"step\":0.01,\"statePath\":\"amount\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/elements/amount-display\",\"value\":{\"type\":\"Metric\",\"props\":{\"label\":\"Selected\",\"value\":{\"$path\":\"amount\"},\"unit\":\"BNB\"},\"children\":[]}}\n{\"op\":\"add\",\"path\":\"/elements/addr-input\",\"value\":{\"type\":\"Input\",\"props\":{\"label\":\"Recipient Address\",\"placeholder\":\"0x...\",\"statePath\":\"address\"},\"children\":[],\"validation\":{\"checks\":[{\"fn\":\"required\",\"message\":\"Address is required\"}],\"validateOn\":\"blur\"}}}\n{\"op\":\"add\",\"path\":\"/elements/send-btn\",\"value\":{\"type\":\"Button\",\"props\":{\"label\":\"Send BNB\",\"variant\":\"primary\"},\"children\":[],\"on\":{\"press\":{\"action\":\"sendBnb\",\"params\":{\"amount\":{\"$path\":\"amount\"},\"address\":{\"$path\":\"address\"}},\"confirm\":{\"title\":\"Confirm transfer\",\"message\":\"Send BNB to this address?\",\"confirmLabel\":\"Send\",\"cancelLabel\":\"Cancel\"}}}}}\n{\"op\":\"add\",\"path\":\"/state/amount\",\"value\":0.1}\n{\"op\":\"add\",\"path\":\"/state/address\",\"value\":\"\"}\n```\n\n---\n\nUser: \"What does BNB stand for?\"\n\nYour response: BNB stands for Binance Coin \u2014 it's the native token of the BNB Chain (formerly Binance Smart Chain).\n\n(text-only reply \u2014 no patches needed)";
+export interface CatalogPromptOptions {
+    /** Extra rules appended to the end of the prompt. */
+    customRules?: string[];
+    /** Include a small example UiSpec at the end. */
+    includeExamples?: boolean;
+    /** Only include these component types (subset of catalog). */
+    componentFilter?: string[];
+    /**
+     * Output mode:
+     *   "generate" (default) — AI outputs ONLY JSONL patches, no prose.
+     *   "chat"               — AI responds conversationally first, then
+     *                          emits JSONL patches on their own lines.
+     */
+    mode?: "generate" | "chat";
+}
+/**
+ * Assembles the full UI catalog system prompt from the static blocks
+ * and a rendered component catalog. Prefer composing the named exports
+ * directly at the call site when you know which sections you need.
+ */
+export declare function generateCatalogPrompt(options?: CatalogPromptOptions): string;
+export {};
+//# sourceMappingURL=ui-catalog-prompt.d.ts.map

package/dist/packages/agent/src/shared/ui-catalog-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-catalog-prompt.d.ts","sourceRoot":"","sources":["../../../../../src/shared/ui-catalog-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAqzB3D,CAAC;AAMF,mEAAmE;AACnE,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,CAAC,EAAE,6BAA6B,GACtC,MAAM,CAyBR;AAMD,gEAAgE;AAChE,eAAO,MAAM,8BAA8B,2JAC0G,CAAC;AAEtJ,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,kjBAIyG,CAAC;AAEjJ,qEAAqE;AACrE,eAAO,MAAM,eAAe,o8CAgC0D,CAAC;AAEvF,4BAA4B;AAC5B,eAAO,MAAM,eAAe,icAO2G,CAAC;AAExI,6BAA6B;AAC7B,eAAO,MAAM,gBAAgB,wRAEuO,CAAC;AAErQ,0BAA0B;AAC1B,eAAO,MAAM,aAAa,siBAqBnB,CAAC;AAER,0BAA0B;AAC1B,eAAO,MAAM,aAAa,wxBAwBW,CAAC;AAEtC,sBAAsB;AACtB,eAAO,MAAM,SAAS,gvBAuBqI,CAAC;AAE5J,uCAAuC;AACvC,eAAO,MAAM,SAAS,kfAewH,CAAC;AAE/I;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAOd,CAAC;AAMf,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,i0CAUzB,CAAC;AAER,6EAA6E;AAC7E,eAAO,MAAM,eAAe,g3DAyBU,CAAC;AAMvC,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,iDAAiD;IACjD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAuB5E"}