@hasna/connectors 1.1.14 → 1.1.15

package/bin/index.js

@@ -10117,6 +10117,24 @@ function migrate(db) {
       created_at TEXT NOT NULL
     )
   `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      id TEXT PRIMARY KEY,
+      resource_type TEXT NOT NULL CHECK(resource_type IN ('connector', 'agent', 'profile', 'token')),
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'exclusive' CHECK(lock_type IN ('advisory', 'exclusive')),
+      locked_at TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at TEXT NOT NULL
+    )
+  `);
+  db.run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
+      ON resource_locks(resource_type, resource_id)
+      WHERE lock_type = 'exclusive'
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at)`);
 }
 var DB_DIR, DB_PATH, _db = null;
 var init_database = __esm(() => {
@@ -10190,6 +10208,78 @@ var init_agents = __esm(() => {
   AGENT_ACTIVE_WINDOW_MS = 30 * 60 * 1000;
 });
 
+// src/db/rate.ts
+function ensureRateTable(db) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS connector_rate_usage (
+      agent_id TEXT NOT NULL,
+      connector TEXT NOT NULL,
+      window_start TEXT NOT NULL,
+      call_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (agent_id, connector, window_start)
+    )
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_rate_usage_window ON connector_rate_usage(connector, window_start)`);
+}
+function countActiveAgents(db) {
+  const cutoff = new Date(Date.now() - AGENT_ACTIVE_WINDOW_MS2).toISOString();
+  const row = db.query("SELECT COUNT(*) as count FROM agents WHERE last_seen_at > ?").get(cutoff);
+  return Math.max(1, row?.count ?? 1);
+}
+function currentWindowStart() {
+  const now3 = Date.now();
+  const windowMs = WINDOW_SECONDS * 1000;
+  return new Date(Math.floor(now3 / windowMs) * windowMs).toISOString();
+}
+function checkRateBudget(agentId, connector, connectorLimit, consume = true, db) {
+  const d = db ?? getDatabase();
+  ensureRateTable(d);
+  const activeAgents = countActiveAgents(d);
+  const budget = Math.max(1, Math.floor(connectorLimit / activeAgents));
+  const windowStart = currentWindowStart();
+  const windowMs = WINDOW_SECONDS * 1000;
+  const windowEnd = new Date(Math.floor(Date.now() / windowMs) * windowMs + windowMs);
+  const windowResetsIn = windowEnd.getTime() - Date.now();
+  const row = d.query("SELECT call_count FROM connector_rate_usage WHERE agent_id = ? AND connector = ? AND window_start = ?").get(agentId, connector, windowStart);
+  const used = row?.call_count ?? 0;
+  if (used >= budget) {
+    return {
+      exceeded: true,
+      connector,
+      agent_id: agentId,
+      budget,
+      used,
+      active_agents: activeAgents,
+      window_resets_in_ms: windowResetsIn,
+      message: `Rate budget exceeded for "${connector}" (${used}/${budget} calls used, ${activeAgents} active agent${activeAgents === 1 ? "" : "s"} sharing limit of ${connectorLimit}/min). Resets in ${Math.ceil(windowResetsIn / 1000)}s.`
+    };
+  }
+  if (consume) {
+    d.run(`INSERT INTO connector_rate_usage (agent_id, connector, window_start, call_count)
+       VALUES (?, ?, ?, 1)
+       ON CONFLICT(agent_id, connector, window_start) DO UPDATE SET call_count = call_count + 1`, [agentId, connector, windowStart]);
+  }
+  return {
+    connector,
+    agent_id: agentId,
+    limit: connectorLimit,
+    active_agents: activeAgents,
+    budget,
+    used: consume ? used + 1 : used,
+    remaining: consume ? budget - used - 1 : budget - used,
+    window_start: windowStart,
+    window_resets_in_ms: windowResetsIn
+  };
+}
+function getRateBudget(agentId, connector, connectorLimit, db) {
+  return checkRateBudget(agentId, connector, connectorLimit, false, db);
+}
+var AGENT_ACTIVE_WINDOW_MS2, WINDOW_SECONDS = 60;
+var init_rate = __esm(() => {
+  init_database();
+  AGENT_ACTIVE_WINDOW_MS2 = 30 * 60 * 1000;
+});
+
 // src/server/serve.ts
 var exports_serve = {};
 __export(exports_serve, {
@@ -10493,6 +10583,14 @@ Dashboard not found at: ${dashboardDir}`);
         deleteAgent(agent.id);
         return json({ success: true }, 200, port);
       }
+      const rateMatch = path.match(/^\/api\/rate\/([^/]+)\/([^/]+)$/);
+      if (rateMatch && method === "GET") {
+        const [, agentId, connector] = rateMatch;
+        const limit = parseInt(url2.searchParams.get("limit") || "60", 10);
+        const consume = url2.searchParams.get("consume") === "true";
+        const result = consume ? checkRateBudget(agentId, connector, limit) : getRateBudget(agentId, connector, limit);
+        return json(result, 200, port);
+      }
       const profilesMatch = path.match(/^\/api\/connectors\/([^/]+)\/profiles$/);
       if (profilesMatch && method === "GET") {
         const name = profilesMatch[1];
@@ -10712,6 +10810,7 @@ Dashboard not found at: ${dashboardDir}`);
 var activityLog, MAX_ACTIVITY_LOG = 100, MIME_TYPES, SECURITY_HEADERS, MAX_BODY_SIZE;
 var init_serve = __esm(() => {
   init_agents();
+  init_rate();
   init_registry();
   init_installer();
   init_auth();

package/bin/mcp.js

@@ -26009,6 +26009,24 @@ function migrate(db) {
       created_at TEXT NOT NULL
     )
   `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      id TEXT PRIMARY KEY,
+      resource_type TEXT NOT NULL CHECK(resource_type IN ('connector', 'agent', 'profile', 'token')),
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'exclusive' CHECK(lock_type IN ('advisory', 'exclusive')),
+      locked_at TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at TEXT NOT NULL
+    )
+  `);
+  db.run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
+      ON resource_locks(resource_type, resource_id)
+      WHERE lock_type = 'exclusive'
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at)`);
 }
 
 // src/db/agents.ts
@@ -26068,10 +26086,79 @@ function listAgents(db) {
   const d = db ?? getDatabase();
   return d.query("SELECT * FROM agents ORDER BY name").all();
 }
+
+// src/db/rate.ts
+var AGENT_ACTIVE_WINDOW_MS2 = 30 * 60 * 1000;
+var WINDOW_SECONDS = 60;
+function ensureRateTable(db) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS connector_rate_usage (
+      agent_id TEXT NOT NULL,
+      connector TEXT NOT NULL,
+      window_start TEXT NOT NULL,
+      call_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (agent_id, connector, window_start)
+    )
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_rate_usage_window ON connector_rate_usage(connector, window_start)`);
+}
+function countActiveAgents(db) {
+  const cutoff = new Date(Date.now() - AGENT_ACTIVE_WINDOW_MS2).toISOString();
+  const row = db.query("SELECT COUNT(*) as count FROM agents WHERE last_seen_at > ?").get(cutoff);
+  return Math.max(1, row?.count ?? 1);
+}
+function currentWindowStart() {
+  const now3 = Date.now();
+  const windowMs = WINDOW_SECONDS * 1000;
+  return new Date(Math.floor(now3 / windowMs) * windowMs).toISOString();
+}
+function checkRateBudget(agentId, connector, connectorLimit, consume = true, db) {
+  const d = db ?? getDatabase();
+  ensureRateTable(d);
+  const activeAgents = countActiveAgents(d);
+  const budget = Math.max(1, Math.floor(connectorLimit / activeAgents));
+  const windowStart = currentWindowStart();
+  const windowMs = WINDOW_SECONDS * 1000;
+  const windowEnd = new Date(Math.floor(Date.now() / windowMs) * windowMs + windowMs);
+  const windowResetsIn = windowEnd.getTime() - Date.now();
+  const row = d.query("SELECT call_count FROM connector_rate_usage WHERE agent_id = ? AND connector = ? AND window_start = ?").get(agentId, connector, windowStart);
+  const used = row?.call_count ?? 0;
+  if (used >= budget) {
+    return {
+      exceeded: true,
+      connector,
+      agent_id: agentId,
+      budget,
+      used,
+      active_agents: activeAgents,
+      window_resets_in_ms: windowResetsIn,
+      message: `Rate budget exceeded for "${connector}" (${used}/${budget} calls used, ${activeAgents} active agent${activeAgents === 1 ? "" : "s"} sharing limit of ${connectorLimit}/min). Resets in ${Math.ceil(windowResetsIn / 1000)}s.`
+    };
+  }
+  if (consume) {
+    d.run(`INSERT INTO connector_rate_usage (agent_id, connector, window_start, call_count)
+       VALUES (?, ?, ?, 1)
+       ON CONFLICT(agent_id, connector, window_start) DO UPDATE SET call_count = call_count + 1`, [agentId, connector, windowStart]);
+  }
+  return {
+    connector,
+    agent_id: agentId,
+    limit: connectorLimit,
+    active_agents: activeAgents,
+    budget,
+    used: consume ? used + 1 : used,
+    remaining: consume ? budget - used - 1 : budget - used,
+    window_start: windowStart,
+    window_resets_in_ms: windowResetsIn
+  };
+}
+function getRateBudget(agentId, connector, connectorLimit, db) {
+  return checkRateBudget(agentId, connector, connectorLimit, false, db);
+}
 // package.json
 var package_default = {
   name: "@hasna/connectors",
-  version: "1.1.13",
+  version: "1.1.14",
   description: "Open source connector library - Install API connectors with a single command",
   type: "module",
   bin: {
@@ -26668,6 +26755,30 @@ server.registerTool("list_agents", {
   const agents = listAgents();
   return { content: [{ type: "text", text: JSON.stringify(agents, null, 2) }] };
 });
+server.registerTool("check_rate_budget", {
+  title: "Check Rate Budget",
+  description: "Consume one rate budget unit for an agent+connector. Returns budget status or RateExceededError.",
+  inputSchema: {
+    agent_id: exports_external.string(),
+    connector: exports_external.string(),
+    limit: exports_external.number().describe("Connector's documented rate limit (calls/min)")
+  }
+}, async ({ agent_id, connector, limit }) => {
+  const result = checkRateBudget(agent_id, connector, limit);
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.registerTool("get_rate_budget", {
+  title: "Get Rate Budget",
+  description: "Peek at rate budget status without consuming a unit.",
+  inputSchema: {
+    agent_id: exports_external.string(),
+    connector: exports_external.string(),
+    limit: exports_external.number().describe("Connector's documented rate limit (calls/min)")
+  }
+}, async ({ agent_id, connector, limit }) => {
+  const result = getRateBudget(agent_id, connector, limit);
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
 async function main() {
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/bin/serve.js

@@ -53,6 +53,24 @@ function migrate(db) {
       created_at TEXT NOT NULL
     )
   `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS resource_locks (
+      id TEXT PRIMARY KEY,
+      resource_type TEXT NOT NULL CHECK(resource_type IN ('connector', 'agent', 'profile', 'token')),
+      resource_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      lock_type TEXT NOT NULL DEFAULT 'exclusive' CHECK(lock_type IN ('advisory', 'exclusive')),
+      locked_at TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at TEXT NOT NULL
+    )
+  `);
+  db.run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
+      ON resource_locks(resource_type, resource_id)
+      WHERE lock_type = 'exclusive'
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at)`);
 }
 
 // src/db/agents.ts
@@ -117,6 +135,75 @@ function deleteAgent(id, db) {
   return d.run("DELETE FROM agents WHERE id = ?", [id]).changes > 0;
 }
 
+// src/db/rate.ts
+var AGENT_ACTIVE_WINDOW_MS2 = 30 * 60 * 1000;
+var WINDOW_SECONDS = 60;
+function ensureRateTable(db) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS connector_rate_usage (
+      agent_id TEXT NOT NULL,
+      connector TEXT NOT NULL,
+      window_start TEXT NOT NULL,
+      call_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (agent_id, connector, window_start)
+    )
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_rate_usage_window ON connector_rate_usage(connector, window_start)`);
+}
+function countActiveAgents(db) {
+  const cutoff = new Date(Date.now() - AGENT_ACTIVE_WINDOW_MS2).toISOString();
+  const row = db.query("SELECT COUNT(*) as count FROM agents WHERE last_seen_at > ?").get(cutoff);
+  return Math.max(1, row?.count ?? 1);
+}
+function currentWindowStart() {
+  const now3 = Date.now();
+  const windowMs = WINDOW_SECONDS * 1000;
+  return new Date(Math.floor(now3 / windowMs) * windowMs).toISOString();
+}
+function checkRateBudget(agentId, connector, connectorLimit, consume = true, db) {
+  const d = db ?? getDatabase();
+  ensureRateTable(d);
+  const activeAgents = countActiveAgents(d);
+  const budget = Math.max(1, Math.floor(connectorLimit / activeAgents));
+  const windowStart = currentWindowStart();
+  const windowMs = WINDOW_SECONDS * 1000;
+  const windowEnd = new Date(Math.floor(Date.now() / windowMs) * windowMs + windowMs);
+  const windowResetsIn = windowEnd.getTime() - Date.now();
+  const row = d.query("SELECT call_count FROM connector_rate_usage WHERE agent_id = ? AND connector = ? AND window_start = ?").get(agentId, connector, windowStart);
+  const used = row?.call_count ?? 0;
+  if (used >= budget) {
+    return {
+      exceeded: true,
+      connector,
+      agent_id: agentId,
+      budget,
+      used,
+      active_agents: activeAgents,
+      window_resets_in_ms: windowResetsIn,
+      message: `Rate budget exceeded for "${connector}" (${used}/${budget} calls used, ${activeAgents} active agent${activeAgents === 1 ? "" : "s"} sharing limit of ${connectorLimit}/min). Resets in ${Math.ceil(windowResetsIn / 1000)}s.`
+    };
+  }
+  if (consume) {
+    d.run(`INSERT INTO connector_rate_usage (agent_id, connector, window_start, call_count)
+       VALUES (?, ?, ?, 1)
+       ON CONFLICT(agent_id, connector, window_start) DO UPDATE SET call_count = call_count + 1`, [agentId, connector, windowStart]);
+  }
+  return {
+    connector,
+    agent_id: agentId,
+    limit: connectorLimit,
+    active_agents: activeAgents,
+    budget,
+    used: consume ? used + 1 : used,
+    remaining: consume ? budget - used - 1 : budget - used,
+    window_start: windowStart,
+    window_resets_in_ms: windowResetsIn
+  };
+}
+function getRateBudget(agentId, connector, connectorLimit, db) {
+  return checkRateBudget(agentId, connector, connectorLimit, false, db);
+}
+
 // src/server/serve.ts
 import { join as join6, dirname as dirname3, extname, basename } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -6979,6 +7066,14 @@ Dashboard not found at: ${dashboardDir}`);
         deleteAgent(agent.id);
         return json({ success: true }, 200, port);
       }
+      const rateMatch = path.match(/^\/api\/rate\/([^/]+)\/([^/]+)$/);
+      if (rateMatch && method === "GET") {
+        const [, agentId, connector] = rateMatch;
+        const limit = parseInt(url2.searchParams.get("limit") || "60", 10);
+        const consume = url2.searchParams.get("consume") === "true";
+        const result = consume ? checkRateBudget(agentId, connector, limit) : getRateBudget(agentId, connector, limit);
+        return json(result, 200, port);
+      }
       const profilesMatch = path.match(/^\/api\/connectors\/([^/]+)\/profiles$/);
       if (profilesMatch && method === "GET") {
         const name = profilesMatch[1];

package/dist/db/database.d.ts

@@ -3,3 +3,5 @@ export declare function getDatabase(path?: string): Database;
 export declare function closeDatabase(): void;
 /** ISO timestamp string */
 export declare function now(): string;
+/** 8-char UUID prefix */
+export declare function shortUuid(): string;

package/dist/db/locks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Resource lock helpers for open-connectors.
+ *
+ * Same interface as open-mementos src/db/locks.ts — standard pattern across
+ * all @hasna apps. Resource types are scoped to what connectors manages:
+ *   connector — the connector itself (install/uninstall ops)
+ *   agent     — agent records
+ *   profile   — connector auth profiles
+ *   token     — OAuth token refresh operations
+ */
+import type { Database } from "bun:sqlite";
+export type ResourceType = "connector" | "agent" | "profile" | "token";
+export type LockType = "advisory" | "exclusive";
+export interface ResourceLock {
+    id: string;
+    resource_type: ResourceType;
+    resource_id: string;
+    agent_id: string;
+    lock_type: LockType;
+    locked_at: string;
+    expires_at: string;
+}
+/**
+ * Acquire a lock on a resource.
+ * - advisory: multiple agents can hold advisory locks simultaneously
+ * - exclusive: only one agent can hold an exclusive lock at a time
+ *
+ * Returns the lock if acquired, null if blocked by an existing exclusive lock.
+ * TTL is in seconds (default: 5 minutes).
+ */
+export declare function acquireLock(agentId: string, resourceType: ResourceType, resourceId: string, lockType?: LockType, ttlSeconds?: number, db?: Database): ResourceLock | null;
+/**
+ * Release a specific lock by ID. Only the owning agent can release it.
+ */
+export declare function releaseLock(lockId: string, agentId: string, db?: Database): boolean;
+/**
+ * Release all locks held by an agent on a specific resource.
+ */
+export declare function releaseResourceLocks(agentId: string, resourceType: ResourceType, resourceId: string, db?: Database): number;
+/**
+ * Release all locks held by an agent (e.g., on session end).
+ */
+export declare function releaseAllAgentLocks(agentId: string, db?: Database): number;
+/**
+ * Check if a resource is currently locked. Returns active lock(s) or empty array.
+ */
+export declare function checkLock(resourceType: ResourceType, resourceId: string, lockType?: LockType, db?: Database): ResourceLock[];
+/**
+ * Check if a specific agent holds a lock on a resource.
+ */
+export declare function agentHoldsLock(agentId: string, resourceType: ResourceType, resourceId: string, lockType?: LockType, db?: Database): ResourceLock | null;
+/**
+ * List all active locks for an agent.
+ */
+export declare function listAgentLocks(agentId: string, db?: Database): ResourceLock[];
+/**
+ * Delete all expired locks. Called automatically by other lock functions.
+ */
+export declare function cleanExpiredLocks(db?: Database): number;

package/dist/db/locks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/rate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent-aware rate budget splitting for connector operations.
+ *
+ * When multiple agents share a connector, the connector's rate limit is split
+ * evenly among active agents (last heartbeat < 30min). Each agent gets:
+ *   budget = Math.floor(connectorRateLimit / activeAgentCount)
+ *
+ * Rate usage is tracked per-agent-per-connector in the DB:
+ *   connector_rate_usage(agent_id, connector, window_start, call_count)
+ *
+ * The window resets every WINDOW_SECONDS (default: 60s = per-minute rate).
+ */
+import type { Database } from "bun:sqlite";
+export interface RateBudget {
+    connector: string;
+    agent_id: string;
+    limit: number;
+    active_agents: number;
+    budget: number;
+    used: number;
+    remaining: number;
+    window_start: string;
+    window_resets_in_ms: number;
+}
+export interface RateExceededError {
+    exceeded: true;
+    connector: string;
+    agent_id: string;
+    budget: number;
+    used: number;
+    active_agents: number;
+    window_resets_in_ms: number;
+    message: string;
+}
+export declare function isRateExceeded(result: RateBudget | RateExceededError): result is RateExceededError;
+/**
+ * Ensure the rate_usage table exists (idempotent).
+ */
+export declare function ensureRateTable(db: Database): void;
+/**
+ * Check and optionally consume one rate budget unit for an agent+connector.
+ *
+ * @param agentId - Agent ID (from agents table)
+ * @param connector - Connector name (e.g. "stripe")
+ * @param connectorLimit - The connector's documented rate limit (calls/min)
+ * @param consume - If true, increment the call counter. If false, just peek.
+ * @param db - Optional DB instance (defaults to singleton)
+ */
+export declare function checkRateBudget(agentId: string, connector: string, connectorLimit: number, consume?: boolean, db?: Database): RateBudget | RateExceededError;
+/**
+ * Get rate budget status without consuming a unit.
+ */
+export declare function getRateBudget(agentId: string, connector: string, connectorLimit: number, db?: Database): RateBudget | RateExceededError;
+/**
+ * Clean up old rate windows (older than 2 windows).
+ */
+export declare function cleanExpiredRateWindows(db?: Database): number;

package/dist/db/rate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/connectors",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "Open source connector library - Install API connectors with a single command",
   "type": "module",
   "bin": {