@okrlinkhub/agent-bridge 0.1.0 → 0.2.0

package/src/component/channels.ts

@@ -0,0 +1,374 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+import type { MutationCtx, QueryCtx } from "./_generated/server.js";
+
+// --- Token hashing utility (shared with gateway.ts) ---
+
+async function hashToken(token: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(token);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// --- Instance verification helper ---
+
+/**
+ * Verify an instance token and return the agent info.
+ * Throws if the token is invalid, expired, or doesn't match the expected app.
+ */
+async function verifyInstanceToken(
+  ctx: QueryCtx | MutationCtx,
+  instanceToken: string,
+  appName: string,
+): Promise<{ agentId: string; appName: string }> {
+  const tokenHash = await hashToken(instanceToken);
+  const instance = await ctx.db
+    .query("agentAppInstances")
+    .withIndex("by_instance_token_hash", (q) =>
+      q.eq("instanceTokenHash", tokenHash),
+    )
+    .unique();
+
+  if (!instance) {
+    throw new Error("Invalid instance token");
+  }
+
+  if (instance.expiresAt < Date.now()) {
+    throw new Error("Instance token has expired");
+  }
+
+  if (instance.appName !== appName) {
+    throw new Error("Token does not match this app");
+  }
+
+  // Verify agent is active
+  const agent = await ctx.db
+    .query("registeredAgents")
+    .withIndex("by_agent_id", (q) => q.eq("agentId", instance.agentId))
+    .unique();
+
+  if (!agent || !agent.isActive) {
+    throw new Error("Agent has been revoked");
+  }
+
+  return { agentId: instance.agentId, appName: instance.appName };
+}
+
+// --- Channel Management ---
+
+/**
+ * Create a channel for an app.
+ * Idempotent: if the channel already exists, returns the existing ID.
+ */
+export const createChannel = mutation({
+  args: {
+    appName: v.string(),
+    channelName: v.string(),
+    description: v.optional(v.string()),
+  },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    // Check if channel already exists
+    const existing = await ctx.db
+      .query("appChannels")
+      .withIndex("by_appName_and_channelName", (q) =>
+        q.eq("appName", args.appName).eq("channelName", args.channelName),
+      )
+      .unique();
+
+    if (existing) {
+      return existing._id;
+    }
+
+    const id = await ctx.db.insert("appChannels", {
+      appName: args.appName,
+      channelName: args.channelName,
+      description: args.description,
+      createdAt: Date.now(),
+      isActive: true,
+    });
+
+    return id;
+  },
+});
+
+/**
+ * List active channels for an app.
+ */
+export const listChannels = query({
+  args: {
+    appName: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      channelName: v.string(),
+      description: v.optional(v.string()),
+      createdAt: v.number(),
+      isActive: v.boolean(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const channels = await ctx.db
+      .query("appChannels")
+      .withIndex("by_appName_and_channelName", (q) =>
+        q.eq("appName", args.appName),
+      )
+      .collect();
+
+    return channels
+      .filter((c) => c.isActive)
+      .map((c) => ({
+        channelName: c.channelName,
+        description: c.description,
+        createdAt: c.createdAt,
+        isActive: c.isActive,
+      }));
+  },
+});
+
+/**
+ * Deactivate a channel (soft delete).
+ */
+export const deactivateChannel = mutation({
+  args: {
+    appName: v.string(),
+    channelName: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const channel = await ctx.db
+      .query("appChannels")
+      .withIndex("by_appName_and_channelName", (q) =>
+        q.eq("appName", args.appName).eq("channelName", args.channelName),
+      )
+      .unique();
+
+    if (!channel) {
+      return false;
+    }
+
+    await ctx.db.patch(channel._id, { isActive: false });
+    return true;
+  },
+});
+
+// --- Message Operations ---
+
+/**
+ * Post a message to a channel.
+ * Requires a valid instanceToken for authentication.
+ */
+export const postMessage = mutation({
+  args: {
+    instanceToken: v.string(),
+    appName: v.string(),
+    channelName: v.string(),
+    payload: v.string(),
+    priority: v.optional(v.number()),
+    ttlMinutes: v.optional(v.number()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    messageId: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    // Verify the agent's identity
+    const verified = await verifyInstanceToken(
+      ctx,
+      args.instanceToken,
+      args.appName,
+    );
+
+    // Verify channel exists and is active
+    const channel = await ctx.db
+      .query("appChannels")
+      .withIndex("by_appName_and_channelName", (q) =>
+        q.eq("appName", args.appName).eq("channelName", args.channelName),
+      )
+      .unique();
+
+    if (!channel || !channel.isActive) {
+      throw new Error(
+        `Channel "${args.channelName}" not found or inactive in app "${args.appName}"`,
+      );
+    }
+
+    const ttlMs = (args.ttlMinutes ?? 60) * 60 * 1000;
+    const messageId = crypto.randomUUID();
+    const now = Date.now();
+
+    await ctx.db.insert("channelMessages", {
+      appName: args.appName,
+      channelName: args.channelName,
+      messageId,
+      fromAgentId: verified.agentId,
+      payload: args.payload,
+      metadata: {
+        priority: args.priority ?? 5,
+        ttl: ttlMs,
+      },
+      sentAt: now,
+      expiresAt: now + ttlMs,
+      readBy: [],
+    });
+
+    return { success: true, messageId };
+  },
+});
+
+/**
+ * Read messages from a channel with cursor-based pagination.
+ * Filters out expired messages. Returns messages in descending order (newest first).
+ */
+export const readMessages = query({
+  args: {
+    instanceToken: v.string(),
+    appName: v.string(),
+    channelName: v.string(),
+    limit: v.optional(v.number()),
+    after: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      messageId: v.string(),
+      fromAgentId: v.string(),
+      payload: v.string(),
+      metadata: v.object({
+        priority: v.number(),
+        ttl: v.number(),
+      }),
+      sentAt: v.number(),
+      expiresAt: v.number(),
+      readBy: v.array(v.string()),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    // Verify the agent's identity
+    await verifyInstanceToken(ctx, args.instanceToken, args.appName);
+
+    const now = Date.now();
+    const limit = args.limit ?? 20;
+
+    let messagesQuery;
+    if (args.after !== undefined) {
+      messagesQuery = ctx.db
+        .query("channelMessages")
+        .withIndex("by_appName_and_channelName_and_sentAt", (q) =>
+          q
+            .eq("appName", args.appName)
+            .eq("channelName", args.channelName)
+            .gt("sentAt", args.after!),
+        );
+    } else {
+      messagesQuery = ctx.db
+        .query("channelMessages")
+        .withIndex("by_appName_and_channelName_and_sentAt", (q) =>
+          q
+            .eq("appName", args.appName)
+            .eq("channelName", args.channelName),
+        );
+    }
+
+    const messages = await messagesQuery.order("desc").take(limit * 2);
+
+    // Filter out expired messages and take the requested limit
+    const validMessages = messages
+      .filter((m) => m.expiresAt > now)
+      .slice(0, limit);
+
+    return validMessages.map((m) => ({
+      messageId: m.messageId,
+      fromAgentId: m.fromAgentId,
+      payload: m.payload,
+      metadata: m.metadata,
+      sentAt: m.sentAt,
+      expiresAt: m.expiresAt,
+      readBy: m.readBy,
+    }));
+  },
+});
+
+/**
+ * Mark a message as read by an agent.
+ * Adds the agentId to the readBy array if not already present.
+ */
+export const markAsRead = mutation({
+  args: {
+    instanceToken: v.string(),
+    appName: v.string(),
+    messageId: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const verified = await verifyInstanceToken(
+      ctx,
+      args.instanceToken,
+      args.appName,
+    );
+
+    // Find the message by messageId
+    const messages = await ctx.db
+      .query("channelMessages")
+      .withIndex("by_appName_and_channelName_and_sentAt", (q) =>
+        q.eq("appName", args.appName),
+      )
+      .collect();
+
+    const message = messages.find((m) => m.messageId === args.messageId);
+
+    if (!message) {
+      return false;
+    }
+
+    if (message.readBy.includes(verified.agentId)) {
+      // Already marked as read
+      return true;
+    }
+
+    await ctx.db.patch(message._id, {
+      readBy: [...message.readBy, verified.agentId],
+    });
+
+    return true;
+  },
+});
+
+/**
+ * Get count of unread messages for an agent on a channel.
+ * Only counts non-expired messages.
+ */
+export const getUnreadCount = query({
+  args: {
+    instanceToken: v.string(),
+    appName: v.string(),
+    channelName: v.string(),
+  },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const verified = await verifyInstanceToken(
+      ctx,
+      args.instanceToken,
+      args.appName,
+    );
+
+    const now = Date.now();
+
+    const messages = await ctx.db
+      .query("channelMessages")
+      .withIndex("by_appName_and_channelName_and_sentAt", (q) =>
+        q
+          .eq("appName", args.appName)
+          .eq("channelName", args.channelName),
+      )
+      .collect();
+
+    const unread = messages.filter(
+      (m) => m.expiresAt > now && !m.readBy.includes(verified.agentId),
+    );
+
+    return unread.length;
+  },
+});

package/src/component/circuitBreaker.ts

@@ -0,0 +1,250 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+// --- Helpers ---
+
+/**
+ * Get the current hour window string (e.g. "2026-02-08T14").
+ */
+function getCurrentWindowHour(): string {
+  return new Date().toISOString().slice(0, 13);
+}
+
+/**
+ * Calculate seconds remaining until the current hour window expires.
+ */
+export function secondsUntilWindowExpires(): number {
+  const now = new Date();
+  const nextHour = new Date(now);
+  nextHour.setMinutes(0, 0, 0);
+  nextHour.setHours(nextHour.getHours() + 1);
+  return Math.ceil((nextHour.getTime() - now.getTime()) / 1000);
+}
+
+// --- Validators ---
+
+const checkResultValidator = v.object({
+  allowed: v.boolean(),
+  reason: v.optional(v.string()),
+  currentCount: v.number(),
+  currentTokens: v.number(),
+});
+
+const statusValidator = v.object({
+  agentId: v.string(),
+  appName: v.string(),
+  windowHour: v.string(),
+  requestCount: v.number(),
+  tokenEstimate: v.number(),
+  isBlocked: v.boolean(),
+  blockedReason: v.optional(v.string()),
+  blockedAt: v.optional(v.number()),
+});
+
+// --- Public functions ---
+
+/**
+ * Check the circuit breaker and increment counters if allowed.
+ * This is designed to be called from within the gateway's authorizeRequest
+ * mutation, but is also exposed for direct use.
+ *
+ * Looks up or creates the counter for the current hour window, checks
+ * if the agent is already blocked, then increments request count and
+ * token estimate. If limits are exceeded, blocks the agent for the
+ * remainder of the hour window.
+ */
+export const checkAndIncrement = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    estimatedCost: v.number(),
+    limits: v.object({
+      requestsPerHour: v.number(),
+      tokenBudget: v.number(),
+    }),
+  },
+  returns: checkResultValidator,
+  handler: async (ctx, args) => {
+    const windowHour = getCurrentWindowHour();
+
+    // Find or create counter for this window
+    let counter = await ctx.db
+      .query("circuitCounters")
+      .withIndex("by_agentId_and_appName_and_windowHour", (q) =>
+        q
+          .eq("agentId", args.agentId)
+          .eq("appName", args.appName)
+          .eq("windowHour", windowHour),
+      )
+      .unique();
+
+    if (!counter) {
+      // Create new counter for this window
+      const id = await ctx.db.insert("circuitCounters", {
+        agentId: args.agentId,
+        appName: args.appName,
+        windowHour,
+        requestCount: 0,
+        tokenEstimate: 0,
+        isBlocked: false,
+      });
+      counter = (await ctx.db.get(id))!;
+    }
+
+    // If already blocked, deny immediately
+    if (counter.isBlocked) {
+      return {
+        allowed: false,
+        reason: counter.blockedReason ?? "Circuit breaker is open",
+        currentCount: counter.requestCount,
+        currentTokens: counter.tokenEstimate,
+      };
+    }
+
+    // Check if this request would exceed limits
+    const newRequestCount = counter.requestCount + 1;
+    const newTokenEstimate = counter.tokenEstimate + args.estimatedCost;
+
+    const requestsExceeded = newRequestCount > args.limits.requestsPerHour;
+    const tokensExceeded = newTokenEstimate > args.limits.tokenBudget;
+
+    if (requestsExceeded || tokensExceeded) {
+      // Block the circuit breaker
+      const reason = requestsExceeded
+        ? `Requests per hour exceeded (${newRequestCount}/${args.limits.requestsPerHour})`
+        : `Token budget exceeded (${newTokenEstimate}/${args.limits.tokenBudget})`;
+
+      await ctx.db.patch(counter._id, {
+        requestCount: newRequestCount,
+        tokenEstimate: newTokenEstimate,
+        isBlocked: true,
+        blockedReason: reason,
+        blockedAt: Date.now(),
+      });
+
+      return {
+        allowed: false,
+        reason,
+        currentCount: newRequestCount,
+        currentTokens: newTokenEstimate,
+      };
+    }
+
+    // Increment counters
+    await ctx.db.patch(counter._id, {
+      requestCount: newRequestCount,
+      tokenEstimate: newTokenEstimate,
+    });
+
+    return {
+      allowed: true,
+      currentCount: newRequestCount,
+      currentTokens: newTokenEstimate,
+    };
+  },
+});
+
+/**
+ * Get the current circuit breaker status for an agent on an app.
+ * Returns the counter for the current hour window.
+ */
+export const getStatus = query({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+  },
+  returns: v.union(statusValidator, v.null()),
+  handler: async (ctx, args) => {
+    const windowHour = getCurrentWindowHour();
+
+    const counter = await ctx.db
+      .query("circuitCounters")
+      .withIndex("by_agentId_and_appName_and_windowHour", (q) =>
+        q
+          .eq("agentId", args.agentId)
+          .eq("appName", args.appName)
+          .eq("windowHour", windowHour),
+      )
+      .unique();
+
+    if (!counter) {
+      return null;
+    }
+
+    return {
+      agentId: counter.agentId,
+      appName: counter.appName,
+      windowHour: counter.windowHour,
+      requestCount: counter.requestCount,
+      tokenEstimate: counter.tokenEstimate,
+      isBlocked: counter.isBlocked,
+      blockedReason: counter.blockedReason,
+      blockedAt: counter.blockedAt,
+    };
+  },
+});
+
+/**
+ * Admin function to manually reset a blocked circuit breaker.
+ * Creates a fresh counter for the current window with zeroed values.
+ */
+export const resetCounter = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const windowHour = getCurrentWindowHour();
+
+    const counter = await ctx.db
+      .query("circuitCounters")
+      .withIndex("by_agentId_and_appName_and_windowHour", (q) =>
+        q
+          .eq("agentId", args.agentId)
+          .eq("appName", args.appName)
+          .eq("windowHour", windowHour),
+      )
+      .unique();
+
+    if (!counter) {
+      return false;
+    }
+
+    await ctx.db.patch(counter._id, {
+      requestCount: 0,
+      tokenEstimate: 0,
+      isBlocked: false,
+      blockedReason: undefined,
+      blockedAt: undefined,
+    });
+
+    return true;
+  },
+});
+
+/**
+ * List all currently blocked circuit breakers.
+ * Useful for admin dashboards.
+ */
+export const listBlocked = query({
+  args: {},
+  returns: v.array(statusValidator),
+  handler: async (ctx) => {
+    const blocked = await ctx.db
+      .query("circuitCounters")
+      .withIndex("by_isBlocked", (q) => q.eq("isBlocked", true))
+      .collect();
+
+    return blocked.map((c) => ({
+      agentId: c.agentId,
+      appName: c.appName,
+      windowHour: c.windowHour,
+      requestCount: c.requestCount,
+      tokenEstimate: c.tokenEstimate,
+      isBlocked: c.isBlocked,
+      blockedReason: c.blockedReason,
+      blockedAt: c.blockedAt,
+    }));
+  },
+});