hive-intelligence 1.6.3 → 1.7.1

package/build/server.js

@@ -6,7 +6,7 @@ import {
   ensureWallet,
   executeToolByName,
   getWalletStatus
-} from "./chunk-XZJICKAL.js";
+} from "./chunk-2C5FBG7B.js";
 import {
   CategoryEndpoints,
   HERO_TOOL_NAMES,
@@ -35,6 +35,7 @@ import {
   createOAuthStore,
   createToolNotFoundResult,
   endpointAllowedForInvoker,
+  errorDocUrl,
   executeEndpoint,
   getAllWrappedEndpoints,
   getAnalyticsWriter,
@@ -64,6 +65,7 @@ import {
   heroTools,
   isB2BSubjectsEnabled,
   isEndpointInvokerName,
+  isFreeWriteEndpoint,
   isHiveOAuthAccessToken,
   isProduction,
   isRedisAvailable,
@@ -74,6 +76,7 @@ import {
   listKeys,
   materializeSubjectContext,
   normalizeInvokeArgs,
+  principalKeyFromRaw,
   recordProviderCanary,
   recordSubjectAuditEvent,
   resolveEndpoint,
@@ -87,19 +90,21 @@ import {
   runProviderCanaryQuick,
   runTaskCanariesQuick,
   runTaskCanary,
+  runWithRequestPrincipal,
   runWithSubjectContext,
   runWorkflowRegressionCanaries,
   secureLogger,
+  submitFeedback,
   trackCliCommand,
   trackOAuthFirstMaterialReceipt,
   trackServerEvent,
   validateEndpointArgs,
   verifyApiKey,
   waitForRedisAvailability
-} from "./chunk-IJ5KOZH5.js";
+} from "./chunk-3SQPLZW6.js";
 import {
   HIVE_AGENT_SKILLS
-} from "./chunk-GADPH72D.js";
+} from "./chunk-4QDGA6GP.js";
 import "./chunk-EPF36Q3Z.js";
 import {
   PUBLIC_MCP_REGISTRY_ID,
@@ -762,19 +767,6 @@ import rateLimit from "express-rate-limit";
 import RedisStore from "rate-limit-redis";
 
 // src/utils/api-errors.ts
-var ERROR_DOC_BASE = "https://www.hiveintelligence.xyz/errors";
-var ERROR_DOC_URLS = {
-  MISSING_PARAM: `${ERROR_DOC_BASE}#missing-param`,
-  TOOL_NOT_FOUND: `${ERROR_DOC_BASE}#tool-not-found`,
-  TOOL_ERROR: `${ERROR_DOC_BASE}#tool-error`,
-  PROVIDER_UNAVAILABLE: `${ERROR_DOC_BASE}#provider-unavailable`,
-  RATE_LIMITED: `${ERROR_DOC_BASE}#rate-limited`,
-  INTERNAL_ERROR: `${ERROR_DOC_BASE}#internal-error`,
-  ENDPOINT_NOT_FOUND: `${ERROR_DOC_BASE}#endpoint-not-found`,
-  SHUTTING_DOWN: `${ERROR_DOC_BASE}#shutting-down`,
-  UNAUTHORIZED: `${ERROR_DOC_BASE}#unauthorized`,
-  VALIDATION_ERROR: `${ERROR_DOC_BASE}#validation-error`
-};
 function apiError(type, code, message, opts) {
   return {
     ok: false,
@@ -784,7 +776,11 @@ function apiError(type, code, message, opts) {
       message,
       ...opts?.param && { param: opts.param },
       ...opts?.requestId && { request_id: opts.requestId },
-      doc_url: ERROR_DOC_URLS[code] ?? `${ERROR_DOC_BASE}#${code.toLowerCase().replace(/_/g, "-")}`
+      ...opts?.cause && { cause: opts.cause },
+      ...opts?.next_action && { next_action: opts.next_action },
+      ...opts?.retryable !== void 0 && { retryable: opts.retryable },
+      ...opts?.retry_after !== void 0 && { retry_after: opts.retry_after },
+      doc_url: errorDocUrl(code)
     }
   };
 }
@@ -7191,8 +7187,10 @@ function classifyAnonymousMcpRequest(body) {
     return "auth_required";
   }
   if (exposedToolName.startsWith("hive_")) return "auth_required";
+  if (isFreeWriteEndpoint(exposedToolName)) return "open";
   if (isEndpointInvokerName(exposedToolName)) {
     const target = getInvokeEndpointName(body?.params?.arguments);
+    if (target && isFreeWriteEndpoint(target)) return "open";
     if (target?.startsWith("hive_")) return "auth_required";
     return "material";
   }
@@ -7413,6 +7411,13 @@ function createStatelessMcpHandler(scope) {
       } else if (decision.kind === "quota_exhausted") {
         res.setHeader("Retry-After", String(decision.resetSeconds));
         const exhaustedMessage = decision.scope === "global" ? ANON_GLOBAL_CAP_MESSAGE : ANON_QUOTA_EXHAUSTED_MESSAGE;
+        const exhaustedCode = decision.scope === "global" ? "ANON_GLOBAL_CAP_EXCEEDED" : "ANON_QUOTA_EXCEEDED";
+        recordPaywall(req, {
+          code: exhaustedCode,
+          authLane: "anonymous",
+          transport: "mcp",
+          toolName: req.body?.params?.name
+        });
         if (mcpOAuth.status === "ready") {
           const requiredScopes = getRequiredMcpScopes(req.body);
           res.setHeader(
@@ -7434,9 +7439,12 @@ function createStatelessMcpHandler(scope) {
             code: -32001,
             message: exhaustedMessage,
             data: {
-              code: decision.scope === "global" ? "ANON_GLOBAL_CAP_EXCEEDED" : "ANON_QUOTA_EXCEEDED",
+              code: exhaustedCode,
               retryable: true,
-              retry_after: decision.resetSeconds
+              retry_after: decision.resetSeconds,
+              cause: decision.scope === "global" ? "Hive's shared keyless allowance for today is spent." : "This IP's 25 free material calls for today are spent.",
+              next_action: "Set HIVE_API_KEY (free at https://hiveintelligence.xyz/dashboard/keys) or sign in via OAuth; keys are not subject to the keyless cap.",
+              doc_url: errorDocUrl(exhaustedCode)
             }
           },
           id: req.body?.id ?? null
@@ -7668,6 +7676,7 @@ function createStatelessMcpHandler(scope) {
         } : void 0,
         beforeToolExecution: keyedAuth?.userId ? async (executedToolName) => {
           const creditCost = getMcpCreditCost(executedToolName);
+          let keyedBalance;
           res.setHeader("X-Hive-Credit-Cost", String(creditCost));
           if (creditCost > 0) {
             const debit = await debitMcpCredits({
@@ -7687,7 +7696,16 @@ function createStatelessMcpHandler(scope) {
                   next_action: "Visit https://hiveintelligence.xyz/dashboard to initialize billing, or contact support. Retrying will not help until the wallet exists."
                 };
               }
-              if (debit.rateLimited) res.setHeader("Retry-After", "60");
+              if (debit.rateLimited) {
+                res.setHeader("Retry-After", "60");
+                recordPaywall(req, {
+                  code: "QUOTA_EXCEEDED",
+                  authLane: keyedAuth.authMethod,
+                  transport: "mcp",
+                  principalRaw: keyedAuth.userId,
+                  toolName: executedToolName
+                });
+              }
               return {
                 type: debit.rateLimited ? "rate_limit_error" : "internal_error",
                 code: debit.rateLimited ? "QUOTA_EXCEEDED" : "QUOTA_SERVICE_UNAVAILABLE",
@@ -7701,6 +7719,7 @@ function createStatelessMcpHandler(scope) {
               "X-Quota-Remaining",
               debit.balance === null ? "unlimited" : String(debit.balance)
             );
+            keyedBalance = debit.balance;
           }
           if (subjectContext) {
             const materialized = await materializeSubjectContext(subjectContext);
@@ -7725,12 +7744,24 @@ function createStatelessMcpHandler(scope) {
             requestId: req.requestId
           });
           if (auditEvent) recordSubjectAuditEvent(auditEvent);
-          return void 0;
+          return {
+            type: "billing",
+            credits_used: creditCost,
+            ...creditCost > 0 && { credits_remaining: keyedBalance }
+          };
         } : anonymousLane ? async (executedToolName) => {
           const creditCost = getMcpCreditCost(executedToolName);
           res.setHeader("X-Hive-Credit-Cost", String(creditCost));
-          if (creditCost === 0) return void 0;
+          if (creditCost === 0) {
+            return { type: "billing", credits_used: 0 };
+          }
           if (!anonymousLane.materialGranted || executedToolName.startsWith("hive_")) {
+            recordPaywall(req, {
+              code: "ANON_AUTH_REQUIRED",
+              authLane: "anonymous",
+              transport: "mcp",
+              toolName: executedToolName
+            });
             return {
               type: "authentication_error",
               code: "ANON_AUTH_REQUIRED",
@@ -7738,7 +7769,11 @@ function createStatelessMcpHandler(scope) {
               runtimeStatus: "failing"
             };
           }
-          return void 0;
+          return {
+            type: "billing",
+            credits_used: creditCost,
+            credits_remaining: anonymousLane.quotaRemaining ?? null
+          };
         } : void 0
       }).getServer();
       const transport = new StreamableHTTPServerTransport({
@@ -7752,7 +7787,17 @@ function createStatelessMcpHandler(scope) {
       await server.connect(transport);
       await runWithSubjectContext(
         subjectContext,
-        () => transport.handleRequest(req, res, body)
+        () => runWithRequestPrincipal(
+          analytics.principalRaw && analytics.authLane ? {
+            key: principalKeyFromRaw(
+              analytics.principalRaw,
+              analytics.authLane
+            ),
+            lane: analytics.authLane,
+            client: analytics.clientName ?? null
+          } : void 0,
+          () => transport.handleRequest(req, res, body)
+        )
       );
       secureLogger.debug("MCP request completed", {
         sessionId: sessionCorrelationId,
@@ -7968,6 +8013,161 @@ var REST_EXECUTE_STATUS_CODES = {
   STATE_SUBJECT_ARCHIVED: 410,
   STATE_BACKEND_UNAVAILABLE: 503
 };
+function restErrorOptionsFromReceipt(meta) {
+  return {
+    ...meta.cause && { cause: meta.cause },
+    ...meta.next_action && { next_action: meta.next_action },
+    retryable: meta.runtime_status === "rate_limited" || meta.runtime_status === "degraded" || meta.runtime_status === "failing"
+  };
+}
+function recordPaywall(req, event) {
+  try {
+    getAnalyticsWriter().enqueuePaywall({
+      code: event.code,
+      authLane: event.authLane,
+      transport: event.transport,
+      principalRaw: event.principalRaw ?? `anon:${anonymousIpHash(ipRateLimitKeyFromRequest(req))}`,
+      toolName: typeof event.toolName === "string" ? event.toolName : null,
+      isInternal: isMonitorSecretRequest(req)
+    });
+  } catch {
+  }
+}
+async function resolveOptionalRestPrincipal(req) {
+  if (mcpCredentialPresented(req)) {
+    const auth = await validateMcpCredential(req);
+    if (!auth.ok) {
+      return {
+        ok: false,
+        status: 401,
+        code: "UNAUTHORIZED",
+        message: "The credential presented was rejected."
+      };
+    }
+    const principalId = auth.userId ?? auth.keyId ?? "static";
+    return {
+      ok: true,
+      key: `user:${principalId}`,
+      lane: auth.authMethod,
+      userId: auth.userId
+    };
+  }
+  return {
+    ok: true,
+    key: `anon:${anonymousIpHash(ipRateLimitKeyFromRequest(req))}`,
+    lane: "anonymous"
+  };
+}
+app.post("/api/v1/feedback", async (req, res) => {
+  const principal = await resolveOptionalRestPrincipal(req);
+  if (!principal.ok) {
+    res.status(principal.status).json(
+      apiError("authentication_error", principal.code, principal.message, {
+        requestId: req.requestId
+      })
+    );
+    return;
+  }
+  const body = req.body ?? {};
+  const result = await submitFeedback({
+    principalKey: principal.key,
+    lane: principal.lane,
+    client: typeof body.client === "string" ? body.client : null,
+    message: body.message,
+    tool: body.tool,
+    receiptId: body.receipt_id
+  });
+  if (result.ok) {
+    res.json({
+      ok: true,
+      data: { id: result.id, remaining_today: result.remaining, reset_at: result.resetAt }
+    });
+    return;
+  }
+  const status = result.code === "VALIDATION_ERROR" ? 400 : result.code === "FEEDBACK_RATE_LIMITED" ? 429 : 503;
+  if (result.resetAt) {
+    const seconds = Math.max(
+      1,
+      Math.round((Date.parse(result.resetAt) - Date.now()) / 1e3)
+    );
+    res.setHeader("Retry-After", String(seconds));
+  }
+  res.status(status).json({
+    ...apiError(
+      result.code === "VALIDATION_ERROR" ? "invalid_request_error" : result.code === "FEEDBACK_RATE_LIMITED" ? "rate_limit_error" : "internal_error",
+      result.code,
+      result.message,
+      {
+        requestId: req.requestId,
+        retryable: result.retryable,
+        ...result.resetAt && {
+          next_action: `Retry after ${result.resetAt}.`
+        }
+      }
+    ),
+    ...result.resetAt && { reset_at: result.resetAt }
+  });
+});
+app.get("/api/v1/quota", async (req, res) => {
+  const principal = await resolveOptionalRestPrincipal(req);
+  if (!principal.ok) {
+    res.status(principal.status).json(
+      apiError("authentication_error", principal.code, principal.message, {
+        requestId: req.requestId
+      })
+    );
+    return;
+  }
+  try {
+    if (principal.lane === "anonymous") {
+      if (!isSupabaseConfigured()) {
+        res.json({
+          ok: true,
+          data: { lane: "anonymous", remaining: null, limit: getAnonDailyMaterialCap(), reset_at: null }
+        });
+        return;
+      }
+      const { data, error } = await getSupabaseAdmin().rpc(
+        "read_anon_daily_quota",
+        {
+          p_ip_hash: anonymousIpHash(ipRateLimitKeyFromRequest(req)),
+          p_ip_limit: getAnonDailyMaterialCap()
+        }
+      );
+      if (error) throw new Error(error.message);
+      const row = Array.isArray(data) ? data[0] : data;
+      const resetSeconds = Math.max(1, row?.reset_seconds ?? 1);
+      res.json({
+        ok: true,
+        data: {
+          lane: "anonymous",
+          remaining: row?.remaining ?? null,
+          limit: row?.limit_value ?? getAnonDailyMaterialCap(),
+          reset_at: new Date(Date.now() + resetSeconds * 1e3).toISOString()
+        }
+      });
+      return;
+    }
+    const wallet = principal.userId ? await getWalletStatus(principal.userId) : null;
+    res.json({
+      ok: true,
+      data: {
+        lane: principal.lane,
+        remaining: wallet ? wallet.balance : null,
+        limit: wallet ? wallet.monthlyGrant : null,
+        reset_at: wallet ? wallet.cycleEnd : null
+      }
+    });
+  } catch (error) {
+    secureLogger.error("Quota read failed", error, { requestId: req.requestId });
+    res.status(503).json(
+      apiError("internal_error", "QUOTA_SERVICE_UNAVAILABLE", "The quota read is unavailable right now.", {
+        requestId: req.requestId,
+        retryable: true
+      })
+    );
+  }
+});
 function buildRestExecutionMeta(toolName, durationMs, meta) {
   return {
     tool: toolName,
@@ -7990,6 +8190,14 @@ function buildRestExecutionMeta(toolName, durationMs, meta) {
     origin_source: meta.origin_source,
     truncated: meta.truncated,
     warnings: meta.warnings,
+    ...meta.credit_cost !== void 0 && { credit_cost: meta.credit_cost },
+    ...meta.credits_used !== void 0 && { credits_used: meta.credits_used },
+    ...meta.credits_remaining !== void 0 && {
+      credits_remaining: meta.credits_remaining
+    },
+    ...meta.cause && { cause: meta.cause },
+    ...meta.next_action && { next_action: meta.next_action },
+    ...meta.doc_url && { doc_url: meta.doc_url },
     // Agent-actionable copy travels on every transport, not only MCP: REST and
     // CLI callers were getting "not found" with no replacement (2026-09-14).
     ...meta.cause !== void 0 && { cause: meta.cause },
@@ -8086,13 +8294,27 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
         return;
       }
       const globalCap = quota.reason === "global_cap";
+      const capCode = globalCap ? "ANON_GLOBAL_CAP_EXCEEDED" : "ANON_QUOTA_EXCEEDED";
+      recordPaywall(req, {
+        code: capCode,
+        authLane: "anonymous",
+        transport: "rest",
+        principalRaw: `anon:${ipHash}`,
+        toolName
+      });
       res.setHeader("Retry-After", String(quota.resetSeconds));
       res.status(429).json(
         apiError(
           "rate_limit_error",
-          globalCap ? "ANON_GLOBAL_CAP_EXCEEDED" : "ANON_QUOTA_EXCEEDED",
+          capCode,
           globalCap ? ANON_GLOBAL_CAP_MESSAGE : ANON_QUOTA_EXHAUSTED_MESSAGE,
-          { requestId: req.requestId }
+          {
+            requestId: req.requestId,
+            cause: globalCap ? "Hive's shared keyless allowance for today is spent." : "This IP's free material calls for today are spent.",
+            next_action: "Set HIVE_API_KEY (free at https://hiveintelligence.xyz/dashboard/keys); keys are not subject to the keyless cap.",
+            retryable: true,
+            retry_after: quota.resetSeconds
+          }
         )
       );
       return;
@@ -8102,6 +8324,12 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
       transport: "rest",
       requestId: req.requestId,
       clients: getSharedClients(),
+      creditCost: getMcpCreditCost(toolName),
+      beforeExecution: async () => ({
+        type: "billing",
+        credits_used: getMcpCreditCost(toolName),
+        credits_remaining: quota.remaining
+      }),
       analytics: {
         principalRaw: `anon:${ipHash}`,
         authLane: "anonymous",
@@ -8125,7 +8353,8 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
     };
     res.status(REST_EXECUTE_STATUS_CODES[error.code] ?? 500).json({
       ...apiError(error.type, error.code, error.message, {
-        requestId: req.requestId
+        requestId: req.requestId,
+        ...restErrorOptionsFromReceipt(result.hive)
       }),
       meta,
       ...result.validationErrors && {
@@ -8163,7 +8392,18 @@ app.post(
     const endpointArgs = authReq.resolvedRestToolArgs ?? { ...args ?? {} };
     const keyedBeforeExecution = async (endpoint) => {
       const blocked = await debitApiKeyCreditForExecution(req, res);
-      if (blocked) return blocked;
+      if (blocked) {
+        if (blocked.code === "QUOTA_EXCEEDED") {
+          recordPaywall(req, {
+            code: "QUOTA_EXCEEDED",
+            authLane: "api_key",
+            transport: "rest",
+            principalRaw: authReq.userId,
+            toolName: endpoint.tool.name
+          });
+        }
+        return blocked;
+      }
       authReq.idempotencyExecutionStarted = true;
       if (authReq.hiveSubjectContext) {
         const materialized = await materializeSubjectContext(
@@ -8190,7 +8430,15 @@ app.post(
         requestId: req.requestId
       });
       if (restAuditEvent) recordSubjectAuditEvent(restAuditEvent);
-      return void 0;
+      const remainingHeader = res.getHeader("X-Quota-Remaining");
+      const creditCost = getMcpCreditCost(endpoint.tool.name);
+      return {
+        type: "billing",
+        credits_used: creditCost,
+        ...creditCost > 0 && remainingHeader !== void 0 && {
+          credits_remaining: String(remainingHeader) === "unlimited" ? null : Number(remainingHeader)
+        }
+      };
     };
     const heroEndpoint = HERO_TOOL_NAMES.has(executionToolName) ? getRestHeroEndpoint(executionToolName) : void 0;
     const result = heroEndpoint ? await (async () => {
@@ -8198,6 +8446,7 @@ app.post(
         transport: "rest",
         requestId: req.requestId,
         clients: getSharedClients(),
+        creditCost: getMcpCreditCost(executionToolName),
         analytics: {
           principalRaw: authReq.userId,
           authLane: "api_key",
@@ -8215,17 +8464,21 @@ app.post(
       };
     })() : await runWithSubjectContext(
       authReq.hiveSubjectContext,
-      () => executeToolByName(executionToolName, endpointArgs, {
-        requestId: req.requestId,
-        // Same identity context the hero branch passes — without it every
-        // non-hero keyed REST call wrote a NULL-principal analytics row.
-        analytics: {
-          principalRaw: authReq.userId,
-          authLane: "api_key",
-          isInternal: isMonitorSecretRequest(req)
-        },
-        beforeExecution: keyedBeforeExecution
-      })
+      () => runWithRequestPrincipal(
+        authReq.userId ? { key: `user:${authReq.userId}`, lane: "api_key", client: null } : void 0,
+        () => executeToolByName(executionToolName, endpointArgs, {
+          requestId: req.requestId,
+          creditCost: getMcpCreditCost(executionToolName),
+          // Same identity context the hero branch passes — without it every
+          // non-hero keyed REST call wrote a NULL-principal analytics row.
+          analytics: {
+            principalRaw: authReq.userId,
+            authLane: "api_key",
+            isInternal: isMonitorSecretRequest(req)
+          },
+          beforeExecution: keyedBeforeExecution
+        })
+      )
     );
     const meta = buildRestExecutionMeta(
       executionToolName,
@@ -8239,7 +8492,8 @@ app.post(
     const status = REST_EXECUTE_STATUS_CODES[error.code] ?? 500;
     return res.status(status).json({
       ...apiError(error.type, error.code, error.message, {
-        requestId: req.requestId
+        requestId: req.requestId,
+        ...restErrorOptionsFromReceipt(result.meta)
       }),
       meta,
       ...result.validationErrors && {

package/build/stdio.js

@@ -6,8 +6,8 @@ import {
 import {
   createHiveMcpServer,
   secureLogger
-} from "./chunk-IJ5KOZH5.js";
-import "./chunk-GADPH72D.js";
+} from "./chunk-3SQPLZW6.js";
+import "./chunk-4QDGA6GP.js";
 import "./chunk-EPF36Q3Z.js";
 import {
   SERVER_NAME,