@okrlinkhub/agent-factory 0.1.0

package/src/component/lib.test.ts

@@ -0,0 +1,319 @@
+/// <reference types="vite/client" />
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { api, internal } from "./_generated/api.js";
+import { initConvexTest } from "./setup.test.js";
+
+describe("component lib", () => {
+  beforeEach(async () => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  test("enqueue and claim should respect queue flow", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "support-agent",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: ["telegram.botToken"],
+      enabled: true,
+    });
+
+    const messageId = await t.mutation(api.lib.enqueue, {
+      conversationId: "telegram:chat:1",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u1",
+        messageText: "Ciao",
+      },
+    });
+    expect(messageId).toBeDefined();
+
+    const claimed = await t.mutation(api.lib.claim, {
+      workerId: "worker-1",
+    });
+    expect(claimed).not.toBeNull();
+    expect(claimed?.conversationId).toBe("telegram:chat:1");
+  });
+
+  test("identity binding should resolve, rebind and revoke", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "agent-a",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: [],
+      enabled: true,
+    });
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "agent-b",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: [],
+      enabled: true,
+    });
+
+    const first = await t.mutation(api.lib.bindUserAgent, {
+      consumerUserId: "u-1",
+      agentKey: "agent-a",
+      source: "telegram_pairing",
+      telegramUserId: "tg-user-1",
+      telegramChatId: "tg-chat-1",
+    });
+    expect(first.agentKey).toBe("agent-a");
+
+    const byUser = await t.query(api.lib.resolveAgentForUser, {
+      consumerUserId: "u-1",
+    });
+    expect(byUser.agentKey).toBe("agent-a");
+
+    const byTelegram = await t.query(api.lib.resolveAgentForTelegram, {
+      telegramUserId: "tg-user-1",
+    });
+    expect(byTelegram.agentKey).toBe("agent-a");
+
+    await t.mutation(api.lib.bindUserAgent, {
+      consumerUserId: "u-1",
+      agentKey: "agent-b",
+      source: "manual",
+      telegramUserId: "tg-user-1",
+      telegramChatId: "tg-chat-1",
+    });
+
+    const rebound = await t.query(api.lib.resolveAgentForUser, {
+      consumerUserId: "u-1",
+    });
+    expect(rebound.agentKey).toBe("agent-b");
+
+    const revokeResult = await t.mutation(api.lib.revokeUserAgentBinding, {
+      consumerUserId: "u-1",
+    });
+    expect(revokeResult.revoked).toBe(1);
+
+    const afterRevoke = await t.query(api.lib.resolveAgentForTelegram, {
+      telegramChatId: "tg-chat-1",
+    });
+    expect(afterRevoke.agentKey).toBeNull();
+  });
+
+  test("worker scheduling should set idle shutdown from completion time", async () => {
+    const t = initConvexTest();
+    const now = Date.now();
+    vi.setSystemTime(now);
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "support-agent",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: [],
+      enabled: true,
+    });
+    const messageId = await t.mutation(api.lib.enqueue, {
+      conversationId: "telegram:chat:2",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u2",
+        messageText: "ciao",
+      },
+    });
+    const claim = await t.mutation(api.lib.claim, { workerId: "worker-2" });
+    expect(claim).not.toBeNull();
+    expect(claim?.messageId).toBe(messageId);
+
+    const completionTime = now + 60_000;
+    vi.setSystemTime(completionTime);
+    const completed = await t.mutation(api.lib.complete, {
+      workerId: "worker-2",
+      messageId,
+      leaseId: claim?.leaseId ?? "",
+    });
+    expect(completed).toBe(true);
+    const workers = await t.query((internal.queue as any).listWorkersForScheduler, {});
+    const worker = workers.find((row: { workerId: string }) => row.workerId === "worker-2");
+    expect(worker?.status).toBe("active");
+    expect(worker?.load).toBe(0);
+    expect(worker?.scheduledShutdownAt).toBe(completionTime + 300_000);
+  });
+
+  test("worker control state should signal stop for stopped worker", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-stop-1",
+      provider: "fly",
+      status: "stopped",
+      load: 0,
+    });
+    const control = await t.query(api.queue.getWorkerControlState as any, {
+      workerId: "worker-stop-1",
+    });
+    expect(control.shouldStop).toBe(true);
+
+    const controlUnknown = await t.query(api.queue.getWorkerControlState as any, {
+      workerId: "worker-nonexistent",
+    });
+    expect(controlUnknown.shouldStop).toBe(true);
+  });
+
+  test("scheduler caps desired workers by distinct ready conversations", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "support-agent",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: [],
+      enabled: true,
+    });
+    await t.mutation(api.queue.importPlaintextSecret, {
+      secretRef: "fly.apiToken",
+      plaintextValue: "fly-token",
+    });
+    await t.mutation(api.queue.importPlaintextSecret, {
+      secretRef: "convex.url",
+      plaintextValue: "https://example.convex.cloud",
+    });
+
+    await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:cap-1",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-cap",
+        messageText: "first",
+      },
+    });
+    await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:cap-1",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-cap",
+        messageText: "second",
+      },
+    });
+
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-1",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-2",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-3",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+
+    const reconcile = await t.action(api.scheduler.reconcileWorkerPool, {
+      scalingPolicy: {
+        minWorkers: 0,
+        maxWorkers: 5,
+        queuePerWorkerTarget: 1,
+        spawnStep: 1,
+        idleTimeoutMs: 300_000,
+        reconcileIntervalMs: 15_000,
+      },
+    });
+    expect(reconcile.desiredWorkers).toBe(1);
+  });
+
+  test("scheduler desired workers increases with distinct ready conversations", async () => {
+    const t = initConvexTest();
+    await t.mutation(api.queue.upsertAgentProfile, {
+      agentKey: "support-agent",
+      version: "1.0.0",
+      soulMd: "# Soul",
+      clientMd: "# Client",
+      skills: ["agent-bridge"],
+      secretsRef: [],
+      enabled: true,
+    });
+    await t.mutation(api.queue.importPlaintextSecret, {
+      secretRef: "fly.apiToken",
+      plaintextValue: "fly-token",
+    });
+    await t.mutation(api.queue.importPlaintextSecret, {
+      secretRef: "convex.url",
+      plaintextValue: "https://example.convex.cloud",
+    });
+
+    await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:cap-a",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-cap-a",
+        messageText: "hello",
+      },
+    });
+    await t.mutation(api.queue.enqueueMessage, {
+      conversationId: "telegram:chat:cap-b",
+      agentKey: "support-agent",
+      payload: {
+        provider: "telegram",
+        providerUserId: "u-cap-b",
+        messageText: "hello",
+      },
+    });
+
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-4",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-5",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+    await t.mutation(internal.queue.upsertWorkerState, {
+      workerId: "worker-cap-6",
+      provider: "fly",
+      status: "active",
+      load: 0,
+    });
+
+    const reconcile = await t.action(api.scheduler.reconcileWorkerPool, {
+      scalingPolicy: {
+        minWorkers: 0,
+        maxWorkers: 5,
+        queuePerWorkerTarget: 1,
+        spawnStep: 1,
+        idleTimeoutMs: 300_000,
+        reconcileIntervalMs: 15_000,
+      },
+      providerConfig: {
+        kind: "fly",
+        appName: "agent-factory-workers",
+        organizationSlug: "personal",
+        image: "registry.fly.io/agent-factory-workers:test-image",
+        region: "iad",
+        volumeName: "",
+        volumePath: "",
+        volumeSizeGb: 10,
+      },
+    });
+    expect(reconcile.desiredWorkers).toBe(2);
+  });
+});

package/src/component/lib.ts

@@ -0,0 +1,30 @@
+export {
+  upsertAgentProfile as configureAgent,
+  importPlaintextSecret as importSecret,
+  getSecretsStatus as secretStatus,
+  enqueueMessage as enqueue,
+  appendConversationMessages,
+  generateMediaUploadUrl,
+  getStorageFileUrl,
+  attachMessageMetadata,
+  claimNextJob as claim,
+  heartbeatJob as heartbeat,
+  completeJob as complete,
+  failJob as fail,
+  getHydrationBundleForClaimedJob as getHydrationBundle,
+  getQueueStats as queueStats,
+  getWorkerStats as workerStats,
+} from "./queue.js";
+
+export { reconcileWorkerPool as reconcileWorkers } from "./scheduler.js";
+
+export {
+  bindUserAgent,
+  revokeUserAgentBinding,
+  resolveAgentForUser,
+  resolveAgentForTelegram,
+  getUserAgentBinding,
+  createPairingCode,
+  consumePairingCode,
+  getPairingCodeStatus,
+} from "./identity.js";

package/src/component/providers/fly.ts

@@ -0,0 +1,226 @@
+export type WorkerProviderStatus =
+  | "active"
+  | "stopped";
+
+export type SpawnWorkerInput = {
+  workerId: string;
+  appName: string;
+  image: string;
+  region: string;
+  volumeName: string;
+  volumePath: string;
+  volumeSizeGb: number;
+  cpuKind?: string;
+  cpus?: number;
+  memoryMb?: number;
+  env?: Record<string, string>;
+};
+
+export type ProviderWorker = {
+  workerId: string;
+  machineId: string;
+  region?: string;
+  image?: string;
+  status: WorkerProviderStatus;
+};
+
+export interface WorkerProvider {
+  spawnWorker(input: SpawnWorkerInput): Promise<ProviderWorker>;
+  listWorkers(appName: string): Promise<Array<ProviderWorker>>;
+  terminateWorker(appName: string, machineId: string): Promise<void>;
+  cordonWorker(appName: string, machineId: string): Promise<void>;
+}
+
+type FlyMachine = {
+  id: string;
+  name?: string;
+  region?: string;
+  state?: string;
+  config?: {
+    image?: string;
+    image_ref?: string;
+  };
+};
+
+type FlyMachineMount = {
+  volume: string;
+  path: string;
+};
+
+type FlyVolume = {
+  id: string;
+  name: string;
+  region?: string;
+};
+
+export class FlyMachinesProvider implements WorkerProvider {
+  constructor(
+    private readonly apiToken: string,
+    private readonly baseUrl: string = "https://api.machines.dev/v1",
+  ) {}
+
+  async spawnWorker(input: SpawnWorkerInput): Promise<ProviderWorker> {
+    const volumeId = await this.resolveOrCreateVolumeId(
+      input.appName,
+      input.volumeName,
+      input.workerId,
+      input.region,
+      input.volumeSizeGb,
+    );
+    const payload = {
+      name: input.workerId,
+      region: input.region,
+      config: {
+        image: input.image,
+        guest: {
+          cpu_kind: input.cpuKind ?? "shared",
+          cpus: input.cpus ?? 1,
+          memory_mb: input.memoryMb ?? 2048,
+        },
+        mounts: [
+          {
+            volume: volumeId,
+            path: input.volumePath,
+          } satisfies FlyMachineMount,
+        ],
+        env: {
+          AGENT_FACTORY_WORKER_ID: input.workerId,
+          ...input.env,
+        },
+      },
+    };
+    const machine = await this.request<FlyMachine>({
+      path: `/apps/${encodeURIComponent(input.appName)}/machines`,
+      method: "POST",
+      body: payload,
+    });
+    return {
+      workerId: input.workerId,
+      machineId: machine.id,
+      region: machine.region ?? input.region,
+      image: machine.config?.image_ref ?? machine.config?.image ?? input.image,
+      status: mapFlyStateToProviderStatus(machine.state),
+    };
+  }
+
+  private async resolveOrCreateVolumeId(
+    appName: string,
+    volumeNamePrefix: string,
+    workerId: string,
+    region: string,
+    volumeSizeGb: number,
+  ): Promise<string> {
+    const volumeName = buildDedicatedVolumeName(volumeNamePrefix, workerId);
+    const volumes = await this.request<Array<FlyVolume>>({
+      path: `/apps/${encodeURIComponent(appName)}/volumes`,
+      method: "GET",
+    });
+    const regionalMatch = volumes.find(
+      (volume) => volume.name === volumeName && volume.region === region,
+    );
+    if (regionalMatch) {
+      return regionalMatch.id;
+    }
+    const created = await this.request<FlyVolume>({
+      path: `/apps/${encodeURIComponent(appName)}/volumes`,
+      method: "POST",
+      body: {
+        name: volumeName,
+        region,
+        size_gb: volumeSizeGb,
+      },
+    });
+    return created.id;
+  }
+
+  async listWorkers(appName: string): Promise<Array<ProviderWorker>> {
+    const machines = await this.request<Array<FlyMachine>>({
+      path: `/apps/${encodeURIComponent(appName)}/machines`,
+      method: "GET",
+    });
+    return machines.map((machine) => ({
+      workerId: machine.name ?? machine.id,
+      machineId: machine.id,
+      region: machine.region,
+      image: machine.config?.image_ref ?? machine.config?.image,
+      status: mapFlyStateToProviderStatus(machine.state),
+    }));
+  }
+
+  async terminateWorker(appName: string, machineId: string): Promise<void> {
+    await this.request<void>({
+      path: `/apps/${encodeURIComponent(appName)}/machines/${encodeURIComponent(machineId)}`,
+      method: "DELETE",
+    });
+  }
+
+  async cordonWorker(appName: string, machineId: string): Promise<void> {
+    await this.request<void>({
+      path: `/apps/${encodeURIComponent(appName)}/machines/${encodeURIComponent(machineId)}/cordon`,
+      method: "POST",
+    });
+  }
+
+  private async request<T>(input: {
+    path: string;
+    method: "GET" | "POST" | "DELETE";
+    body?: unknown;
+  }): Promise<T> {
+    const response = await fetch(`${this.baseUrl}${input.path}`, {
+      method: input.method,
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`,
+        "Content-Type": "application/json",
+      },
+      body: input.body ? JSON.stringify(input.body) : undefined,
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Fly API ${input.method} ${input.path} failed: ${text}`);
+    }
+
+    if (input.method === "DELETE") {
+      return undefined as T;
+    }
+    return (await response.json()) as T;
+  }
+}
+
+function mapFlyStateToProviderStatus(state: string | undefined): WorkerProviderStatus {
+  switch (state) {
+    case "created":
+    case "started":
+      return "active";
+    case "stopped":
+    case "destroyed":
+    case "suspended":
+      return "stopped";
+    default:
+      return "stopped";
+  }
+}
+
+function buildDedicatedVolumeName(prefix: string, workerId: string): string {
+  const sanitize = (value: string) =>
+    value
+      .toLowerCase()
+      .replace(/[^a-z0-9_]/g, "_")
+      .replace(/_+/g, "_")
+      .replace(/^_+|_+$/g, "");
+  const normalizedPrefix = sanitize(prefix) || "openclaw";
+  const normalizedWorker = sanitize(workerId) || "worker";
+  const workerHash = stableHashBase36(normalizedWorker).slice(0, 8);
+  const maxPrefixLen = 30 - 1 - workerHash.length;
+  const trimmedPrefix = normalizedPrefix.slice(0, Math.max(1, maxPrefixLen));
+  return `${trimmedPrefix}_${workerHash}`;
+}
+
+function stableHashBase36(input: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  const unsigned = hash >>> 0;
+  return unsigned.toString(36);
+}