@saleso.innovations/bridge 0.1.15 → 0.1.17

package/dist/hermesFileCommands.js

@@ -0,0 +1,61 @@
+import { DEFAULT_FILES_READ_MAX_BYTES, listHermesFiles, readHermesFileBytes, } from "./hermesFiles.js";
+import { uploadFileToConvex } from "./convexRelay.js";
+import { loadCredentials } from "./credentials.js";
+function optionalNumber(args, key) {
+    const value = args[key];
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function optionalCategory(args) {
+    const value = args.category;
+    if (typeof value !== "string")
+        return "all";
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "image" || normalized === "video" || normalized === "document") {
+        return normalized;
+    }
+    return "all";
+}
+export async function executeFilesList(args) {
+    const limit = optionalNumber(args, "limit");
+    const offset = optionalNumber(args, "offset");
+    const category = optionalCategory(args);
+    return listHermesFiles({ limit, offset, category });
+}
+export async function executeFilesRead(args) {
+    const path = typeof args.path === "string" ? args.path.trim() : "";
+    const maxBytes = optionalNumber(args, "maxBytes") ?? DEFAULT_FILES_READ_MAX_BYTES;
+    const { bytes, mimeType, fileName, size } = readHermesFileBytes(path);
+    if (size <= maxBytes) {
+        return {
+            fileName,
+            mimeType,
+            size,
+            contentBase64: bytes.toString("base64"),
+        };
+    }
+    const credentials = loadCredentials();
+    const agentId = credentials?.agentId;
+    if (!agentId) {
+        throw new Error("Large files require bridge credentials with agentId for Convex upload.");
+    }
+    const uploaded = await uploadFileToConvex({
+        agentId,
+        fileName,
+        mimeType,
+        contentBase64: bytes.toString("base64"),
+    });
+    return {
+        fileName,
+        mimeType,
+        size,
+        storageId: uploaded.storageId,
+        url: uploaded.url ?? undefined,
+    };
+}

package/dist/hermesFiles.d.ts

@@ -0,0 +1,60 @@
+export declare const MAX_RELAY_UPLOAD_BYTES: number;
+export declare const DEFAULT_FILES_READ_MAX_BYTES: number;
+export type HermesFileCategory = "image" | "video" | "document" | "other";
+export type HermesFileEntry = {
+    relativePath: string;
+    fileName: string;
+    size: number;
+    mtime: number;
+    mimeType: string;
+    category: HermesFileCategory;
+};
+export type HermesFileReadResult = {
+    fileName: string;
+    mimeType: string;
+    size: number;
+    contentBase64?: string;
+    storageId?: string;
+    url?: string;
+};
+export type MediaReference = {
+    kind: "local";
+    absolutePath: string;
+    raw: string;
+} | {
+    kind: "url";
+    url: string;
+    raw: string;
+};
+export declare function resolveHermesHome(): string;
+export declare function inferMimeType(fileName: string): string;
+export declare function inferCategory(fileName: string): HermesFileCategory;
+export declare function resolveSandboxedPath(inputPath: string): string;
+export declare function listHermesFiles(options?: {
+    limit?: number;
+    offset?: number;
+    category?: HermesFileCategory | "all";
+}): {
+    files: HermesFileEntry[];
+};
+export declare function readHermesFileBytes(inputPath: string): {
+    bytes: Buffer;
+    mimeType: string;
+    fileName: string;
+    size: number;
+};
+export declare function parseMediaReferences(text: string): MediaReference[];
+export declare function stripMediaReferences(text: string, refs: MediaReference[]): string;
+export declare function downloadUrlToBytes(url: string, timeoutMs?: number): Promise<{
+    bytes: Buffer;
+    mimeType: string;
+    fileName: string;
+    size: number;
+}>;
+export declare function resolveMediaReferenceBytes(ref: MediaReference): Promise<{
+    bytes: Buffer;
+    mimeType: string;
+    fileName: string;
+    size: number;
+} | null>;
+//# sourceMappingURL=hermesFiles.d.ts.map

package/dist/hermesFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermesFiles.d.ts","sourceRoot":"","sources":["../src/hermesFiles.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AACvD,eAAO,MAAM,4BAA4B,QAAa,CAAC;AAgCvD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1E,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiCtD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAMlE;AAQD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAe9D;AA8DD,wBAAgB,eAAe,CAAC,OAAO,GAAE;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;CAClC,GAAG;IAAE,KAAK,EAAE,eAAe,EAAE,CAAA;CAAE,CAepC;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAe1H;AAMD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CA6BnE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,MAAM,CAMjF;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBtJ;AAED,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CASzJ"}

package/dist/hermesFiles.js

@@ -0,0 +1,266 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, relative, resolve, sep } from "node:path";
+export const MAX_RELAY_UPLOAD_BYTES = 25 * 1024 * 1024;
+export const DEFAULT_FILES_READ_MAX_BYTES = 512 * 1024;
+const HIDDEN_DIR_NAMES = new Set([".git", ".hub"]);
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "tiff", "svg"]);
+const VIDEO_EXTENSIONS = new Set(["mp4", "mov", "webm", "mkv", "avi"]);
+const DOCUMENT_EXTENSIONS = new Set([
+    "pdf",
+    "txt",
+    "md",
+    "csv",
+    "json",
+    "xml",
+    "html",
+    "yaml",
+    "yml",
+    "log",
+    "docx",
+    "xlsx",
+    "pptx",
+    "odt",
+    "ods",
+    "odp",
+    "zip",
+    "rar",
+    "7z",
+    "tar",
+    "gz",
+    "bz2",
+    "epub",
+]);
+export function resolveHermesHome() {
+    return process.env.HERMES_HOME?.trim() || join(homedir(), ".hermes");
+}
+export function inferMimeType(fileName) {
+    const ext = fileName.split(".").pop()?.toLowerCase() ?? "";
+    const map = {
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        bmp: "image/bmp",
+        tiff: "image/tiff",
+        svg: "image/svg+xml",
+        mp4: "video/mp4",
+        mov: "video/quicktime",
+        webm: "video/webm",
+        mkv: "video/x-matroska",
+        avi: "video/x-msvideo",
+        pdf: "application/pdf",
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        json: "application/json",
+        xml: "application/xml",
+        html: "text/html",
+        yaml: "text/yaml",
+        yml: "text/yaml",
+        log: "text/plain",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        zip: "application/zip",
+        epub: "application/epub+zip",
+    };
+    return map[ext] ?? "application/octet-stream";
+}
+export function inferCategory(fileName) {
+    const ext = fileName.split(".").pop()?.toLowerCase() ?? "";
+    if (IMAGE_EXTENSIONS.has(ext))
+        return "image";
+    if (VIDEO_EXTENSIONS.has(ext))
+        return "video";
+    if (DOCUMENT_EXTENSIONS.has(ext))
+        return "document";
+    return "other";
+}
+function isPathInsideRoot(root, candidate) {
+    const normalizedRoot = resolve(root);
+    const normalizedCandidate = resolve(candidate);
+    return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}${sep}`);
+}
+export function resolveSandboxedPath(inputPath) {
+    const home = resolveHermesHome();
+    const candidate = inputPath.startsWith("/") ? resolve(inputPath) : resolve(home, inputPath);
+    let resolved = candidate;
+    try {
+        if (existsSync(candidate)) {
+            resolved = realpathSync(candidate);
+        }
+    }
+    catch {
+        // Fall back to unresolved candidate for not-yet-existing paths.
+    }
+    if (!isPathInsideRoot(home, resolved)) {
+        throw new Error(`Path is outside Hermes home: ${inputPath}`);
+    }
+    return resolved;
+}
+function artifactScanRoots(home) {
+    const roots = [];
+    const direct = [
+        join(home, "cache", "images"),
+        join(home, "cache", "documents"),
+        join(home, "cache", "remote-syncs"),
+        join(home, "browser_recordings"),
+    ];
+    for (const dir of direct) {
+        if (existsSync(dir))
+            roots.push(dir);
+    }
+    const profilesDir = join(home, "profiles");
+    if (existsSync(profilesDir)) {
+        for (const profileName of readdirSync(profilesDir)) {
+            if (profileName.startsWith("."))
+                continue;
+            const imageCache = join(profilesDir, profileName, "image_cache");
+            if (existsSync(imageCache))
+                roots.push(imageCache);
+        }
+    }
+    return roots;
+}
+function walkFiles(rootDir, home, files) {
+    let names;
+    try {
+        names = readdirSync(rootDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name.startsWith(".") && HIDDEN_DIR_NAMES.has(name))
+            continue;
+        const fullPath = join(rootDir, name);
+        let stats;
+        try {
+            stats = statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory()) {
+            walkFiles(fullPath, home, files);
+            continue;
+        }
+        if (!stats.isFile())
+            continue;
+        const relativePath = relative(home, fullPath).replace(/\\/g, "/");
+        const fileName = basename(fullPath);
+        const mimeType = inferMimeType(fileName);
+        files.push({
+            relativePath,
+            fileName,
+            size: stats.size,
+            mtime: stats.mtimeMs,
+            mimeType,
+            category: inferCategory(fileName),
+        });
+    }
+}
+export function listHermesFiles(options = {}) {
+    const home = resolveHermesHome();
+    const limit = options.limit ?? 200;
+    const offset = options.offset ?? 0;
+    const category = options.category ?? "all";
+    const all = [];
+    for (const root of artifactScanRoots(home)) {
+        walkFiles(root, home, all);
+    }
+    const filtered = category === "all" ? all : all.filter((file) => file.category === category);
+    filtered.sort((left, right) => right.mtime - left.mtime);
+    return { files: filtered.slice(offset, offset + limit) };
+}
+export function readHermesFileBytes(inputPath) {
+    const resolved = resolveSandboxedPath(inputPath);
+    if (!existsSync(resolved)) {
+        throw new Error(`File not found: ${inputPath}`);
+    }
+    const stats = statSync(resolved);
+    if (!stats.isFile()) {
+        throw new Error(`Not a file: ${inputPath}`);
+    }
+    if (stats.size > MAX_RELAY_UPLOAD_BYTES) {
+        throw new Error(`File exceeds maximum size (${MAX_RELAY_UPLOAD_BYTES} bytes)`);
+    }
+    const bytes = readFileSync(resolved);
+    const fileName = basename(resolved);
+    return { bytes, mimeType: inferMimeType(fileName), fileName, size: bytes.length };
+}
+const MEDIA_TAG_PATTERN = /MEDIA:(\/[^\s\n\r]+)/g;
+const MARKDOWN_IMAGE_URL_PATTERN = /\[Image:[^\]|]*\|\s*(https?:\/\/[^\]\s]+)\]/gi;
+const BARE_MEDIA_URL_PATTERN = /(https?:\/\/[^\s\n\r]+\.(?:png|jpe?g|gif|webp|mp4|mov|webm|pdf|docx?))/gi;
+export function parseMediaReferences(text) {
+    const refs = [];
+    const seen = new Set();
+    for (const match of text.matchAll(MEDIA_TAG_PATTERN)) {
+        const absolutePath = match[1]?.trim();
+        const raw = match[0];
+        if (!absolutePath || seen.has(raw))
+            continue;
+        seen.add(raw);
+        refs.push({ kind: "local", absolutePath, raw });
+    }
+    for (const match of text.matchAll(MARKDOWN_IMAGE_URL_PATTERN)) {
+        const url = match[1]?.trim();
+        const raw = match[0];
+        if (!url || seen.has(raw))
+            continue;
+        seen.add(raw);
+        refs.push({ kind: "url", url, raw });
+    }
+    for (const match of text.matchAll(BARE_MEDIA_URL_PATTERN)) {
+        const url = match[1]?.trim();
+        const raw = match[0];
+        if (!url || seen.has(raw))
+            continue;
+        seen.add(raw);
+        refs.push({ kind: "url", url, raw });
+    }
+    return refs;
+}
+export function stripMediaReferences(text, refs) {
+    let cleaned = text;
+    for (const ref of refs) {
+        cleaned = cleaned.replace(ref.raw, "");
+    }
+    return cleaned.replace(/\n{3,}/g, "\n\n").trim();
+}
+export async function downloadUrlToBytes(url, timeoutMs = 30_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok) {
+            throw new Error(`Failed to download media (${response.status})`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const bytes = Buffer.from(arrayBuffer);
+        if (bytes.length > MAX_RELAY_UPLOAD_BYTES) {
+            throw new Error(`Downloaded file exceeds maximum size (${MAX_RELAY_UPLOAD_BYTES} bytes)`);
+        }
+        const contentType = response.headers.get("content-type")?.split(";")[0]?.trim();
+        const urlPath = new URL(url).pathname;
+        const fileName = basename(urlPath) || "download";
+        const mimeType = contentType && contentType !== "application/octet-stream" ? contentType : inferMimeType(fileName);
+        return { bytes, mimeType, fileName, size: bytes.length };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function resolveMediaReferenceBytes(ref) {
+    try {
+        if (ref.kind === "local") {
+            return readHermesFileBytes(ref.absolutePath);
+        }
+        return await downloadUrlToBytes(ref.url);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/hermesForwarder.d.ts

@@ -5,11 +5,14 @@ export type HermesForwarderOptions = {
     model?: string;
     conversationId?: string;
 };
+export type HermesForwardResult = {
+    sessionId: string;
+};
 export declare function resolveHermesApiConfig(options?: HermesForwarderOptions): {
     apiUrl: string;
     apiKey: string | undefined;
     model: string;
 };
-export declare function forwardToHermes(content: string, meta: UserMessageMeta, reply: AgentReply, options?: HermesForwarderOptions): Promise<void>;
+export declare function forwardToHermes(content: string, meta: UserMessageMeta, reply: AgentReply, options?: HermesForwarderOptions): Promise<HermesForwardResult>;
 export declare function createHermesMessageHandler(options?: HermesForwarderOptions): (content: string, meta: UserMessageMeta, reply: AgentReply) => Promise<void>;
 //# sourceMappingURL=hermesForwarder.d.ts.map

package/dist/hermesForwarder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hermesForwarder.d.ts","sourceRoot":"","sources":["../src/hermesForwarder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAyB,eAAe,EAAE,MAAM,aAAa,CAAC;AAGtF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAkBF,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf,CAUA;AAyID,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,sBAA2B,IAC/D,SAAS,MAAM,EAAE,MAAM,eAAe,EAAE,OAAO,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC,CAMxF"}
+{"version":3,"file":"hermesForwarder.d.ts","sourceRoot":"","sources":["../src/hermesForwarder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAyB,eAAe,EAAE,MAAM,aAAa,CAAC;AAWtF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAkBF,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf,CAUA;AA+MD,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAuE9B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,sBAA2B,IAC/D,SAAS,MAAM,EAAE,MAAM,eAAe,EAAE,OAAO,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC,CAMxF"}

package/dist/hermesForwarder.js

@@ -1,7 +1,10 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { linkHermesMessageIds, uploadFileToConvex } from "./convexRelay.js";
 import { DEFAULT_HERMES_API_URL } from "./constants.js";
+import { getLatestTurnMessageIds, hermesStateDbExists } from "./hermesSessionDb.js";
+import { parseMediaReferences, resolveMediaReferenceBytes, stripMediaReferences, } from "./hermesFiles.js";
 function readHermesApiKeyFromEnvFile() {
     const envPath = join(homedir(), ".hermes", ".env");
     try {
@@ -136,21 +139,89 @@ function buildHermesUserContent(text, attachments) {
     parts.push(...imageParts);
     return parts;
 }
+async function uploadMediaAttachments(agentId, refs) {
+    const attachments = [];
+    for (const ref of refs) {
+        const resolved = await resolveMediaReferenceBytes(ref);
+        if (!resolved)
+            continue;
+        try {
+            const uploaded = await uploadFileToConvex({
+                agentId,
+                fileName: resolved.fileName,
+                mimeType: resolved.mimeType,
+                contentBase64: resolved.bytes.toString("base64"),
+            });
+            attachments.push({
+                storageId: uploaded.storageId,
+                mimeType: uploaded.mimeType,
+                fileName: uploaded.fileName,
+                size: uploaded.size,
+                url: uploaded.url ?? undefined,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(JSON.stringify({ event: "cleos-bridge.media_upload_failed", message }));
+        }
+    }
+    return attachments;
+}
+async function linkTurnToConvex(meta, sessionId) {
+    if (!hermesStateDbExists())
+        return;
+    const { userMessageId, assistantMessageId } = getLatestTurnMessageIds(sessionId);
+    const links = [];
+    if (userMessageId !== undefined) {
+        links.push({
+            clientMessageId: meta.clientMessageId,
+            hermesMessageId: String(userMessageId),
+        });
+    }
+    if (assistantMessageId !== undefined) {
+        links.push({
+            externalMessageId: meta.replyMessageId,
+            hermesMessageId: String(assistantMessageId),
+        });
+    }
+    if (links.length === 0)
+        return;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+            await linkHermesMessageIds({
+                agentId: meta.agentId,
+                conversationId: meta.conversationId,
+                links,
+            });
+            return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (attempt === 4) {
+                console.error(JSON.stringify({ event: "cleos-bridge.hermes_link_failed", message }));
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1)));
+        }
+    }
+}
 export async function forwardToHermes(content, meta, reply, options = {}) {
     const { apiUrl, apiKey, model } = resolveHermesApiConfig(options);
     await ensureHermesReachable(apiUrl, apiKey);
+    const sessionId = options.conversationId ?? meta.conversationId;
     const headers = {
         "content-type": "application/json",
     };
     if (apiKey)
         headers.authorization = `Bearer ${apiKey}`;
-    const conversationKey = options.conversationId ?? meta.conversationId;
+    if (sessionId)
+        headers["X-Hermes-Session-Id"] = sessionId;
     const userContent = buildHermesUserContent(content, meta.attachments);
     const body = {
         model,
         stream: true,
         messages: [{ role: "user", content: userContent }],
-        user: conversationKey,
+        user: sessionId,
     };
     const response = await fetch(apiUrl, {
         method: "POST",
@@ -161,6 +232,7 @@ export async function forwardToHermes(content, meta, reply, options = {}) {
         const text = await response.text();
         throw new Error(`Hermes request failed (${response.status}): ${text}`);
     }
+    const resolvedSessionId = response.headers.get("X-Hermes-Session-Id")?.trim() || sessionId;
     if (!response.body) {
         throw new Error("Hermes returned an empty streaming body");
     }
@@ -187,7 +259,12 @@ export async function forwardToHermes(content, meta, reply, options = {}) {
         reply.delta(fullText, counters.textSequence);
         counters.textSequence += 1;
     }
-    reply.complete(fullText, counters.textSequence);
+    const mediaRefs = parseMediaReferences(fullText);
+    const attachments = mediaRefs.length > 0 ? await uploadMediaAttachments(meta.agentId, mediaRefs) : [];
+    const displayText = attachments.length > 0 ? stripMediaReferences(fullText, mediaRefs) : fullText.trim() || fullText;
+    reply.complete(displayText, counters.textSequence, attachments.length > 0 ? attachments : undefined);
+    await linkTurnToConvex(meta, resolvedSessionId);
+    return { sessionId: resolvedSessionId };
 }
 export function createHermesMessageHandler(options = {}) {
     return async (content, meta, reply) => {

package/dist/hermesSessionDb.d.ts

@@ -0,0 +1,21 @@
+export type HermesSessionMessage = {
+    id: number;
+    sessionId: string;
+    role: string;
+    content: string;
+    timestamp: number;
+};
+export declare function listSessionMessages(sessionId: string, options?: {
+    limit?: number;
+    offset?: number;
+    offsetFromEnd?: number;
+}): HermesSessionMessage[];
+export declare function getLatestTurnMessageIds(sessionId: string): {
+    userMessageId?: number;
+    assistantMessageId?: number;
+};
+export declare function hermesStateDbExists(): boolean;
+export declare function countUserMessagesSent(): {
+    count: number;
+};
+//# sourceMappingURL=hermesSessionDb.d.ts.map

package/dist/hermesSessionDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermesSessionDb.d.ts","sourceRoot":"","sources":["../src/hermesSessionDb.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAgGF,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACxE,oBAAoB,EAAE,CAwCxB;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,CAmCzD;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAO7C;AAED,wBAAgB,qBAAqB,IAAI;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAgBzD"}