@okrlinkhub/agent-factory 3.0.0 → 3.0.2

package/src/component/_generated/component.ts

@@ -583,6 +583,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      createMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actorUserId: string;
+          enabled?: boolean;
+          nowMs?: number;
+          tags: Array<string>;
+          text: string;
+          title: string;
+        },
+        string,
+        Name
+      >;
       createPairingCode: FunctionReference<
         "mutation",
         "internal",
@@ -740,6 +754,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { message: string; ok: boolean; status: number },
         Name
       >;
+      deleteMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        { templateId: string },
+        boolean,
+        Name
+      >;
       deletePushJob: FunctionReference<
         "mutation",
         "internal",
@@ -1253,6 +1274,25 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { secretId: string; secretRef: string; version: number },
         Name
       >;
+      listMessageTemplatesByCompany: FunctionReference<
+        "query",
+        "internal",
+        { includeDisabled?: boolean; limit?: number },
+        Array<{
+          _id: string;
+          createdAt: number;
+          createdBy: string;
+          enabled: boolean;
+          tags: Array<string>;
+          templateKey: string;
+          text: string;
+          title: string;
+          updatedAt: number;
+          updatedBy: string;
+          usageCount: number;
+        }>,
+        Name
+      >;
       listPushDispatchesByJob: FunctionReference<
         "query",
         "internal",
@@ -1632,6 +1672,29 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      sendMessageTemplateToUserAgent: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          agentKey: string;
+          consumerUserId: string;
+          metadata?: Record<string, string>;
+          nowMs?: number;
+          providerConfig?: {
+            appName: string;
+            image: string;
+            kind: "fly" | "runpod" | "ecs";
+            organizationSlug: string;
+            region: string;
+            volumeName: string;
+            volumePath: string;
+            volumeSizeGb: number;
+          };
+          templateId: string;
+        },
+        { messageId: string; usageCount: number },
+        Name
+      >;
       sendMessageToUserAgent: FunctionReference<
         "mutation",
         "internal",
@@ -1736,6 +1799,21 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { enqueuedMessageId: string; runKey: string },
         Name
       >;
+      updateMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actorUserId: string;
+          enabled?: boolean;
+          nowMs?: number;
+          tags?: Array<string>;
+          templateId: string;
+          text?: string;
+          title?: string;
+        },
+        boolean,
+        Name
+      >;
       updatePushJob: FunctionReference<
         "mutation",
         "internal",
@@ -1817,6 +1895,63 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    messageTemplates: {
+      createMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actorUserId: string;
+          enabled?: boolean;
+          nowMs?: number;
+          tags: Array<string>;
+          text: string;
+          title: string;
+        },
+        string,
+        Name
+      >;
+      deleteMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        { templateId: string },
+        boolean,
+        Name
+      >;
+      listMessageTemplatesByCompany: FunctionReference<
+        "query",
+        "internal",
+        { includeDisabled?: boolean; limit?: number },
+        Array<{
+          _id: string;
+          createdAt: number;
+          createdBy: string;
+          enabled: boolean;
+          tags: Array<string>;
+          templateKey: string;
+          text: string;
+          title: string;
+          updatedAt: number;
+          updatedBy: string;
+          usageCount: number;
+        }>,
+        Name
+      >;
+      updateMessageTemplate: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actorUserId: string;
+          enabled?: boolean;
+          nowMs?: number;
+          tags?: Array<string>;
+          templateId: string;
+          text?: string;
+          title?: string;
+        },
+        boolean,
+        Name
+      >;
+    };
     providers: {
       fly: {
         deleteFlyVolumeManual: FunctionReference<
@@ -2949,6 +3084,29 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { requeued: number; unlocked: number },
         Name
       >;
+      sendMessageTemplateToUserAgent: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          agentKey: string;
+          consumerUserId: string;
+          metadata?: Record<string, string>;
+          nowMs?: number;
+          providerConfig?: {
+            appName: string;
+            image: string;
+            kind: "fly" | "runpod" | "ecs";
+            organizationSlug: string;
+            region: string;
+            volumeName: string;
+            volumePath: string;
+            volumeSizeGb: number;
+          };
+          templateId: string;
+        },
+        { messageId: string; usageCount: number },
+        Name
+      >;
       sendMessageToUserAgent: FunctionReference<
         "mutation",
         "internal",

package/src/component/lib.test.ts

@@ -201,6 +201,131 @@ describe("component lib", () => {
     expect(claim?.payload.messageText).toBe("hello");
   });
 
+  test("message templates should normalize tags and auto-generate key", async () => {
+    const t = initConvexTest();
+
+    const templateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "  Status Update ",
+      text: "  Share your latest progress. ",
+      tags: [" Urgent ", "follow-up", "urgent", " Team "],
+      actorUserId: "user-admin-1",
+    });
+
+    expect(templateId).toBeDefined();
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(templates).toHaveLength(1);
+    expect(templates[0]).toMatchObject({
+      templateKey: "status-update",
+      title: "Status Update",
+      text: "Share your latest progress.",
+      tags: ["follow-up", "team", "urgent"],
+      usageCount: 0,
+      enabled: true,
+    });
+  });
+
+  test("message templates should generate a unique key globally", async () => {
+    const t = initConvexTest();
+
+    const firstTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Daily check-in",
+      text: "Share your update.",
+      tags: [],
+      actorUserId: "user-admin-1",
+    });
+
+    const secondTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Daily check-in",
+      text: "Duplicate title",
+      tags: [],
+      actorUserId: "user-admin-2",
+    });
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(firstTemplateId).toBeDefined();
+    expect(secondTemplateId).toBeDefined();
+    expect(templates.map((template) => template.templateKey).sort()).toEqual([
+      "daily-check-in",
+      "daily-check-in-2",
+    ]);
+  });
+
+  test("message templates should track usage and surface most used templates first", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "template-agent",
+      version: "1.0.0",
+      secretsRef: [],
+      enabled: true,
+    });
+    await t.mutation(api.lib.bindUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      source: "manual",
+      metadata: { companyId: "co-templates" },
+    });
+
+    const firstTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Weekly recap",
+      text: "Condividi il recap della settimana.",
+      tags: ["weekly", "recap"],
+      actorUserId: "user-admin-1",
+    });
+    const secondTemplateId = await t.mutation(api.lib.createMessageTemplate, {
+      title: "Quick nudge",
+      text: "Mandami un aggiornamento rapido.",
+      tags: ["follow-up"],
+      actorUserId: "user-admin-1",
+    });
+
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: firstTemplateId,
+    });
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: firstTemplateId,
+    });
+    await t.mutation((api.lib as any).sendMessageTemplateToUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      templateId: secondTemplateId,
+    });
+
+    const templates = await t.query(api.lib.listMessageTemplatesByCompany, {
+      includeDisabled: true,
+    });
+
+    expect(templates.map((template) => ({
+      title: template.title,
+      usageCount: template.usageCount,
+    }))).toEqual([
+      { title: "Weekly recap", usageCount: 2 },
+      { title: "Quick nudge", usageCount: 1 },
+    ]);
+
+    const queuedItems = await t.query(api.lib.listQueueItemsForUserAgent, {
+      consumerUserId: "user-template-1",
+      agentKey: "template-agent",
+      limit: 10,
+    });
+    expect(queuedItems).toHaveLength(3);
+    expect(queuedItems.map((item) => item.payload.messageText).sort()).toEqual([
+      "Condividi il recap della settimana.",
+      "Condividi il recap della settimana.",
+      "Mandami un aggiornamento rapido.",
+    ].sort());
+  });
+
   test("message runtime config should store telegram attachment retention", async () => {
     const t = initConvexTest();
     await t.mutation(api.lib.setMessageRuntimeConfig, {
@@ -1123,6 +1248,14 @@ describe("component lib", () => {
     const t = initConvexTest();
     const nowMs = Date.UTC(2026, 0, 1, 17, 0, 0);
     vi.setSystemTime(nowMs);
+    let machineCreateBody:
+      | {
+          name?: string;
+          config?: {
+            env?: Record<string, string>;
+          };
+        }
+      | null = null;
     const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = String(input);
       const method = init?.method ?? "GET";
@@ -1148,7 +1281,13 @@ describe("component lib", () => {
         });
       }
       if (url.endsWith(`/apps/${TEST_PROVIDER_CONFIG.appName}/machines`) && method === "POST") {
-        const body = JSON.parse(String(init?.body ?? "{}")) as { name?: string };
+        const body = JSON.parse(String(init?.body ?? "{}")) as {
+          name?: string;
+          config?: {
+            env?: Record<string, string>;
+          };
+        };
+        machineCreateBody = body;
         return jsonResponse({
           id: "machine-new-worker",
           name: body.name,
@@ -1224,6 +1363,28 @@ describe("component lib", () => {
 
     expect(reconcile.spawned).toBe(1);
     expect(reconcile.activeWorkers).toBe(2);
+    const machineCreateEnv = (
+      machineCreateBody as
+        | {
+            config?: {
+              env?: Record<string, string>;
+            };
+          }
+        | null
+    )?.config?.env;
+    expect(machineCreateEnv?.OPENCLAW_CONVERSATION_ID).toBe("telegram:chat:spawn-b");
+    expect(machineCreateEnv?.OPENCLAW_AGENT_KEY).toBe("support-agent");
+
+    const workers = await t.query((internal.queue as any).listWorkersForScheduler, {});
+    const spawnedWorker = workers.find(
+      (row: { workerId: string }) => row.workerId === `afw-${nowMs}-0`,
+    );
+    expect(spawnedWorker?.assignment).toEqual({
+      conversationId: "telegram:chat:spawn-b",
+      agentKey: "support-agent",
+      leaseId: `spawn:afw-${nowMs}-0`,
+      assignedAt: nowMs,
+    });
   });
 
   test("scheduler should forward OpenClaw bridge env to spawned machines", async () => {
@@ -1498,6 +1659,60 @@ describe("component lib", () => {
     });
   });
 
+  test("preassigned workers should claim only their assigned conversation on first claim", async () => {
+    const t = initConvexTest();
+    const nowMs = Date.UTC(2026, 0, 1, 17, 35, 0);
+    vi.setSystemTime(nowMs);
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "support-agent",
+      version: "1.0.0",
+      secretsRef: [],
+      enabled: true,
+    });
+
+    await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:preassign-a",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-preassign-a",
+        messageText: "first",
+      },
+      nowMs,
+    });
+    const messageB = await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:preassign-b",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-preassign-b",
+        messageText: "second",
+      },
+      nowMs: nowMs + 1,
+    });
+
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-preassigned-1",
+      provider: "fly",
+      status: "active",
+      load: 0,
+      nowMs,
+      assignment: {
+        conversationId: "telegram:chat:preassign-b",
+        agentKey: "support-agent",
+        leaseId: "spawn:worker-preassigned-1",
+        assignedAt: nowMs,
+      },
+    });
+
+    const claim = await t.mutation(api.lib.claim, {
+      workerId: "worker-preassigned-1",
+      nowMs: nowMs + 10,
+    });
+    expect(claim?.messageId).toBe(messageB);
+    expect(claim?.conversationId).toBe("telegram:chat:preassign-b");
+  });
+
   test("exclusive ownership should block another worker and let the owner reclaim", async () => {
     const t = initConvexTest();
     const nowMs = Date.UTC(2026, 0, 1, 17, 40, 0);

package/src/component/lib.ts

@@ -23,6 +23,7 @@ export {
   listQueueItemsForUserAgent,
   getConversationViewForUserAgent,
   sendMessageToUserAgent,
+  sendMessageTemplateToUserAgent,
   listSnapshotsForConversation,
   listSnapshotsForUserAgent,
   getLatestSnapshotForUserAgent,
@@ -59,6 +60,13 @@ export {
   getWebhookReadiness,
 } from "./identity.js";
 
+export {
+  createMessageTemplate,
+  updateMessageTemplate,
+  deleteMessageTemplate,
+  listMessageTemplatesByCompany,
+} from "./messageTemplates.js";
+
 export {
   createPushTemplate,
   updatePushTemplate,

package/src/component/messageTemplates.ts

@@ -0,0 +1,205 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+import type { MutationCtx } from "./_generated/server.js";
+
+const messageTemplateViewValidator = v.object({
+  _id: v.id("messageTemplates"),
+  templateKey: v.string(),
+  title: v.string(),
+  text: v.string(),
+  tags: v.array(v.string()),
+  usageCount: v.number(),
+  enabled: v.boolean(),
+  createdBy: v.string(),
+  updatedBy: v.string(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+function normalizeTemplateKey(value: string) {
+  return value.trim().toLowerCase();
+}
+
+function buildTemplateKeyBase(title: string) {
+  const normalized = title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "message-template";
+}
+
+function normalizeTitle(value: string) {
+  return value.trim();
+}
+
+function normalizeText(value: string) {
+  return value.trim();
+}
+
+function normalizeTags(tags: Array<string>) {
+  return Array.from(
+    new Set(
+      tags
+        .map((tag) => tag.trim().toLowerCase())
+        .filter((tag) => tag.length > 0),
+    ),
+  ).sort((left, right) => left.localeCompare(right));
+}
+
+function validateMessageTemplateFields(input: {
+  title?: string;
+  text?: string;
+}) {
+  if (input.title !== undefined && input.title.length === 0) {
+    throw new Error("Template title is required");
+  }
+  if (input.text !== undefined && input.text.length === 0) {
+    throw new Error("Template text is required");
+  }
+}
+
+async function resolveUniqueTemplateKey(
+  ctx: MutationCtx,
+  title: string,
+  currentTemplateId?: string,
+) {
+  const baseKey = buildTemplateKeyBase(title);
+  let candidate = baseKey;
+  let suffix = 2;
+
+  while (true) {
+    const existing = await ctx.db
+      .query("messageTemplates")
+      .withIndex("by_templateKey", (q) => q.eq("templateKey", candidate))
+      .unique();
+    if (!existing || String(existing._id) === currentTemplateId) {
+      return candidate;
+    }
+    candidate = `${baseKey}-${suffix}`;
+    suffix += 1;
+  }
+}
+
+export const createMessageTemplate = mutation({
+  args: {
+    title: v.string(),
+    text: v.string(),
+    tags: v.array(v.string()),
+    enabled: v.optional(v.boolean()),
+    actorUserId: v.string(),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.id("messageTemplates"),
+  handler: async (ctx, args) => {
+    const title = normalizeTitle(args.title);
+    const text = normalizeText(args.text);
+    const tags = normalizeTags(args.tags);
+    validateMessageTemplateFields({ title, text });
+    const templateKey = normalizeTemplateKey(await resolveUniqueTemplateKey(ctx, title));
+
+    const nowMs = args.nowMs ?? Date.now();
+    return await ctx.db.insert("messageTemplates", {
+      templateKey,
+      title,
+      text,
+      tags,
+      usageCount: 0,
+      enabled: args.enabled ?? true,
+      createdBy: args.actorUserId,
+      updatedBy: args.actorUserId,
+      createdAt: nowMs,
+      updatedAt: nowMs,
+    });
+  },
+});
+
+export const updateMessageTemplate = mutation({
+  args: {
+    templateId: v.id("messageTemplates"),
+    title: v.optional(v.string()),
+    text: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    enabled: v.optional(v.boolean()),
+    actorUserId: v.string(),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const template = await ctx.db.get(args.templateId);
+    if (!template) return false;
+
+    const title = args.title !== undefined ? normalizeTitle(args.title) : template.title;
+    const text = args.text !== undefined ? normalizeText(args.text) : template.text;
+    const tags = args.tags !== undefined ? normalizeTags(args.tags) : template.tags;
+    validateMessageTemplateFields({ title, text });
+    const templateKey =
+      title !== template.title
+        ? normalizeTemplateKey(await resolveUniqueTemplateKey(ctx, title, String(template._id)))
+        : template.templateKey;
+
+    const nowMs = args.nowMs ?? Date.now();
+    await ctx.db.patch(template._id, {
+      templateKey,
+      title,
+      text,
+      tags,
+      enabled: args.enabled ?? template.enabled,
+      updatedBy: args.actorUserId,
+      updatedAt: nowMs,
+    });
+    return true;
+  },
+});
+
+export const deleteMessageTemplate = mutation({
+  args: {
+    templateId: v.id("messageTemplates"),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const template = await ctx.db.get(args.templateId);
+    if (!template) return false;
+    await ctx.db.delete(template._id);
+    return true;
+  },
+});
+
+export const listMessageTemplatesByCompany = query({
+  args: {
+    includeDisabled: v.optional(v.boolean()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(messageTemplateViewValidator),
+  handler: async (ctx, args) => {
+    const includeDisabled = args.includeDisabled ?? false;
+    const limit = Math.max(1, Math.min(args.limit ?? 100, 200));
+
+    const rows = includeDisabled
+      ? await ctx.db.query("messageTemplates").take(limit)
+      : await ctx.db
+          .query("messageTemplates")
+          .withIndex("by_enabled", (q) => q.eq("enabled", true))
+          .take(limit);
+
+    rows.sort((left, right) => {
+      if (right.usageCount !== left.usageCount) {
+        return right.usageCount - left.usageCount;
+      }
+      return right.updatedAt - left.updatedAt;
+    });
+    return rows.map((row) => ({
+      _id: row._id,
+      templateKey: row.templateKey,
+      title: row.title,
+      text: row.text,
+      tags: row.tags,
+      usageCount: row.usageCount,
+      enabled: row.enabled,
+      createdBy: row.createdBy,
+      updatedBy: row.updatedBy,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    }));
+  },
+});