@saleso.innovations/bridge 0.1.4 → 0.1.6

package/INTEGRATION.md

@@ -53,6 +53,28 @@ export async function resumeCleosConnection() {
 - Relay routing (Railway) between iOS app and Hermes WebSocket
 - Message history in Convex
 
+## Cron job delivery
+
+When a Hermes cron job completes and should appear in the Cleos **Jobs** tab (not chat), deliver the result over the existing agent WebSocket:
+
+```typescript
+import { reconnectHermesAgent } from "@saleso.innovations/bridge";
+
+const connection = await reconnectHermesAgent({ onUserMessage: handleCleosMessage });
+
+// On cron completion — conversationId is the active Cleos conversation for this agent.
+connection.deliverCronResult(finalText, {
+  conversationId: "<convex-conversation-id>",
+  jobId: job.id,
+  jobName: job.name,
+  runAt: Date.now(),
+});
+```
+
+Cleos routes messages with `metadata.cron` directly to the Jobs inbox. Hermes default cron wrappers (`Cronjob Response: ...`) are also detected automatically.
+
+Store the Cleos `conversationId` when pairing (fetch via Convex `conversations:getActive` for the new `agentId`) so cron delivery has a valid target.
+
 ## What Hermes handles
 
 - Pairing UI (code entry)

package/dist/client.d.ts

@@ -8,20 +8,35 @@ export type ConnectOptions = {
     capabilities?: string[];
     onUserMessage?: (content: string, meta: UserMessageMeta, reply: AgentReply) => Promise<void> | void;
 };
+export type UserMessageAttachment = {
+    storageId: string;
+    mimeType: string;
+    fileName: string;
+    size?: number;
+    url?: string;
+};
 export type UserMessageMeta = {
     agentId: string;
     conversationId: string;
     messageId: string;
+    attachments?: UserMessageAttachment[];
 };
 export type AgentReply = {
     delta: (text: string, sequence: number) => void;
     complete: (text: string, sequence: number) => void;
 };
+export type CronDeliveryMeta = {
+    conversationId: string;
+    jobId: string;
+    jobName: string;
+    runAt?: number;
+};
 export type ConnectResult = {
     agentId: string;
     agentToken: string;
     close: () => void;
     closed: Promise<void>;
+    deliverCronResult: (content: string, meta: CronDeliveryMeta) => void;
 };
 export declare function pairCleosAgent(options: Omit<ConnectOptions, "onUserMessage">): Promise<{
     agentId: string;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAIhG,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrG,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB,CAAC;AA8HF,wBAAsB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA0BD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAcxF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE;IAClD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;CAC5C,GAAG,OAAO,CAAC,aAAa,CAAC,CAc9B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAIhG,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrG,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACtE,CAAC;AAwLF,wBAAsB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA0BD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAcxF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE;IAClD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;CAC5C,GAAG,OAAO,CAAC,aAAa,CAAC,CAc9B"}

package/dist/client.js

@@ -3,6 +3,47 @@ import WebSocket from "ws";
 import { saveCredentials, loadCredentials } from "./credentials.js";
 import { convexSiteUrlFromEnv, resolvePairingCode } from "./resolve.js";
 import { normalizePairingCode } from "./normalizePairingCode.js";
+function parseUserMessageAttachments(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const attachments = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const record = item;
+        const storageId = typeof record.storageId === "string" ? record.storageId : "";
+        const mimeType = typeof record.mimeType === "string" ? record.mimeType : "";
+        const fileName = typeof record.fileName === "string" ? record.fileName : "";
+        if (!storageId || !mimeType || !fileName)
+            continue;
+        attachments.push({
+            storageId,
+            mimeType,
+            fileName,
+            size: typeof record.size === "number" ? record.size : undefined,
+            url: typeof record.url === "string" ? record.url : undefined,
+        });
+    }
+    return attachments.length > 0 ? attachments : undefined;
+}
+function sendCronResult(ws, agentId, content, meta) {
+    ws.send(JSON.stringify({
+        type: "agent.message",
+        agentId,
+        conversationId: meta.conversationId,
+        messageId: randomUUID(),
+        content,
+        sequence: 0,
+        final: true,
+        metadata: {
+            cron: {
+                jobId: meta.jobId,
+                jobName: meta.jobName,
+                runAt: meta.runAt,
+            },
+        },
+    }));
+}
 function createReplySender(ws, agentId, conversationId, messageId) {
     return {
         delta(text, sequence) {
@@ -52,10 +93,11 @@ async function openAgentConnection(options) {
             const content = typeof envelope.content === "string" ? envelope.content : "";
             const agentId = typeof envelope.agentId === "string" ? envelope.agentId : options.agentId;
             const conversationId = typeof envelope.conversationId === "string" ? envelope.conversationId : "unknown";
-            const messageId = typeof envelope.clientMessageId === "string" ? envelope.clientMessageId : randomUUID();
-            const reply = createReplySender(ws, agentId, conversationId, messageId);
+            const attachments = parseUserMessageAttachments(envelope.attachments);
+            const replyMessageId = randomUUID();
+            const reply = createReplySender(ws, agentId, conversationId, replyMessageId);
             if (options.onUserMessage) {
-                await options.onUserMessage(content, { agentId, conversationId, messageId }, reply);
+                await options.onUserMessage(content, { agentId, conversationId, messageId: replyMessageId, attachments }, reply);
                 return;
             }
             const echo = `Echo: ${content}`;
@@ -80,6 +122,12 @@ async function openAgentConnection(options) {
             ws.close();
         },
         closed,
+        deliverCronResult(content, meta) {
+            if (ws.readyState !== WebSocket.OPEN) {
+                throw new Error("Cleos relay connection is not open");
+            }
+            sendCronResult(ws, options.agentId, content, meta);
+        },
     };
 }
 async function resolveRelayTargets(options) {

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,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG/D,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;AAqCD,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAwEf;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;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;AA2ED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAyEf;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

@@ -64,6 +64,32 @@ function extractDeltaFromChunk(payload) {
     const content = delta.content;
     return typeof content === "string" ? content : null;
 }
+function buildHermesUserContent(text, attachments) {
+    const trimmed = text.trim();
+    const imageParts = (attachments ?? [])
+        .filter((attachment) => attachment.mimeType.startsWith("image/") && attachment.url)
+        .map((attachment) => ({
+        type: "image_url",
+        image_url: { url: attachment.url },
+    }));
+    const fileNames = (attachments ?? [])
+        .filter((attachment) => !attachment.mimeType.startsWith("image/"))
+        .map((attachment) => attachment.fileName);
+    let prose = trimmed;
+    if (fileNames.length > 0) {
+        const fileNote = `[Attached files: ${fileNames.join(", ")}]`;
+        prose = prose.length === 0 ? fileNote : `${prose}\n\n${fileNote}`;
+    }
+    if (imageParts.length === 0) {
+        return prose.length === 0 ? "(attachment)" : prose;
+    }
+    const parts = [];
+    if (prose.length > 0) {
+        parts.push({ type: "text", text: prose });
+    }
+    parts.push(...imageParts);
+    return parts;
+}
 export async function forwardToHermes(content, meta, reply, options = {}) {
     const { apiUrl, apiKey, model } = resolveHermesApiConfig(options);
     await ensureHermesReachable(apiUrl, apiKey);
@@ -73,10 +99,11 @@ export async function forwardToHermes(content, meta, reply, options = {}) {
     if (apiKey)
         headers.authorization = `Bearer ${apiKey}`;
     const conversationKey = options.conversationId ?? meta.conversationId;
+    const userContent = buildHermesUserContent(content, meta.attachments);
     const body = {
         model,
         stream: true,
-        messages: [{ role: "user", content }],
+        messages: [{ role: "user", content: userContent }],
         user: conversationKey,
     };
     const response = await fetch(apiUrl, {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { connectHermesAgent, pairCleosAgent, reconnectHermesAgent } from "./client.js";
-export type { AgentReply, ConnectOptions, ConnectResult, UserMessageMeta } from "./client.js";
+export type { AgentReply, ConnectOptions, ConnectResult, CronDeliveryMeta, UserMessageMeta } from "./client.js";
 export { loadCredentials, saveCredentials, credentialsPathForDisplay } from "./credentials.js";
 export type { SavedAgentCredentials } from "./credentials.js";
 export { resolvePairingCode, convexSiteUrlFromEnv } from "./resolve.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC3G,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC3G,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saleso.innovations/bridge",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Connect your Hermes agent to the Cleos iOS app via pairing code.",
   "type": "module",
   "license": "MIT",