@mem9/opencode 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem9/opencode",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "OpenCode memory plugin — cloud-persistent AI agent memory with hybrid vector + keyword search via mem9",
   "type": "module",
   "main": "src/index.ts",

package/src/server/hooks.ts

@@ -3,6 +3,7 @@ import type { IngestMessage, MemoryBackend } from "./backend.ts";
 import type { DebugLogger } from "./debug.ts";
 import { selectMessagesForIngest } from "./ingest/select.ts";
 import { submitMessagesForIngest } from "./ingest/submit.ts";
+import { formatRuntimeQuotaNotice, parseRuntimeQuotaDenied } from "./quota-error.ts";
 import { formatRecallBlock } from "./recall/format.ts";
 import { buildRecallQuery } from "./recall/query.ts";
 import type { SessionTranscriptLoader } from "./session-transcript.ts";
@@ -185,14 +186,16 @@ async function ingestSessionTranscript(
           sessionID,
           messageCount: selectedMessages.length,
         });
-        await submitMessagesForIngest({
+        const result = await submitMessagesForIngest({
           backend,
           messages: transcript,
           sessionID,
           agentID: state.agentID,
           debugLogger: options.debugLogger,
         });
-        state.lastIngestFingerprint = fingerprint;
+        if (result) {
+          state.lastIngestFingerprint = fingerprint;
+        }
       } finally {
         if (state.pendingIngestFingerprint === fingerprint) {
           state.pendingIngestFingerprint = null;
@@ -308,6 +311,18 @@ export function buildHooks(
           output.system.push(block);
         }
       } catch (error) {
+        const quotaDenied = parseRuntimeQuotaDenied(error);
+        if (quotaDenied) {
+          await options.debugLogger?.("recall.quota_denied", {
+            sessionID: input.sessionID,
+            code: quotaDenied.code,
+            actionType: quotaDenied.recommendedAction?.type,
+            hasActionUrl: Boolean(quotaDenied.recommendedAction?.url),
+          });
+          output.system.push(formatRuntimeQuotaNotice(error, "recall paused"));
+          return;
+        }
+
         await options.debugLogger?.("recall.error", {
           sessionID: input.sessionID,
           error: error instanceof Error ? error.message : String(error),

package/src/server/ingest/submit.ts

@@ -1,5 +1,6 @@
 import type { IngestInput, IngestResult, MemoryBackend } from "../backend.ts";
 import type { DebugLogger } from "../debug.ts";
+import { parseRuntimeQuotaDenied } from "../quota-error.ts";
 import { selectMessagesForIngest } from "./select.ts";
 
 export interface SubmitIngestOptions {
@@ -45,6 +46,18 @@ export async function submitMessagesForIngest(
     });
     return result;
   } catch (error) {
+    const quotaDenied = parseRuntimeQuotaDenied(error);
+    if (quotaDenied) {
+      await options.debugLogger?.("ingest.quota_denied", {
+        sessionID: options.sessionID,
+        agentID: options.agentID,
+        code: quotaDenied.code,
+        actionType: quotaDenied.recommendedAction?.type,
+        hasActionUrl: Boolean(quotaDenied.recommendedAction?.url),
+      });
+      return null;
+    }
+
     await options.debugLogger?.("ingest.error", {
       sessionID: options.sessionID,
       agentID: options.agentID,

package/src/server/quota-error.ts

@@ -0,0 +1,259 @@
+export class Mem9HttpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly body: string,
+    readonly data: unknown,
+  ) {
+    super(message);
+    this.name = "Mem9HttpError";
+  }
+}
+
+export interface RuntimeRecommendedAction {
+  providerActionCode?: string;
+  severity?: string;
+  type?: string;
+  url?: string;
+}
+
+export interface RuntimeQuotaDenied {
+  status: number | null;
+  code: string;
+  message: string;
+  meter?: string;
+  quotaGateReason?: string;
+  retryAfterSeconds?: number;
+  recommendedAction?: RuntimeRecommendedAction;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizePositiveInteger(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+
+export function parseJsonOrUndefined(text: string): unknown {
+  if (!text.trim()) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export function messageFromErrorBody(status: number, body: string, data: unknown): string {
+  if (isRecord(data)) {
+    const message = normalizeString(data.message);
+    if (message) {
+      return message;
+    }
+
+    const error = normalizeString(data.error);
+    if (error) {
+      return error;
+    }
+  }
+
+  const text = body.trim();
+  return text || `HTTP ${status}`;
+}
+
+function normalizeRecommendedAction(runtimeQuota: Record<string, unknown>): RuntimeRecommendedAction | null {
+  const nested = isRecord(runtimeQuota.recommendedAction) ? runtimeQuota.recommendedAction : {};
+  const providerActionCode = normalizeString(nested.providerActionCode);
+  const severity = normalizeString(nested.severity);
+  const type = normalizeString(nested.type);
+  const url = normalizeString(nested.url);
+
+  if (!providerActionCode && !severity && !type && !url) {
+    return null;
+  }
+
+  return {
+    ...(providerActionCode ? { providerActionCode } : {}),
+    ...(severity ? { severity } : {}),
+    ...(type ? { type } : {}),
+    ...(url ? { url } : {}),
+  };
+}
+
+function quotaGateReason(runtimeQuota: Record<string, unknown>): string {
+  const quotaGateResult = isRecord(runtimeQuota.quotaGateResult) ? runtimeQuota.quotaGateResult : {};
+  return normalizeString(quotaGateResult.reason);
+}
+
+function retryAfterSeconds(runtimeQuota: Record<string, unknown>): number | null {
+  const direct = normalizePositiveInteger(runtimeQuota.retryAfterSeconds);
+  if (direct !== null) {
+    return direct;
+  }
+
+  const quotaGateResult = isRecord(runtimeQuota.quotaGateResult) ? runtimeQuota.quotaGateResult : {};
+  const postQuotaRateLimit = isRecord(quotaGateResult.postQuotaRateLimit) ? quotaGateResult.postQuotaRateLimit : {};
+  return normalizePositiveInteger(postQuotaRateLimit.retryAfterSeconds);
+}
+
+function isPostQuotaRateLimited(denied: RuntimeQuotaDenied): boolean {
+  return denied.status === 429 ||
+    denied.quotaGateReason === "postQuotaRateLimitExceeded";
+}
+
+function quotaReason(denied: RuntimeQuotaDenied): string {
+  if (isPostQuotaRateLimited(denied)) {
+    return "this API key has reached the temporary request limit for this memory feature";
+  }
+  const providerActionCode = normalizeString(denied.recommendedAction?.providerActionCode);
+  if (providerActionCode === "claimApiKey") {
+    return "the included usage quota for this API key has been used up";
+  }
+  if (providerActionCode === "increaseSpendingLimit") {
+    return "the configured spending limit would be exceeded";
+  }
+  if (providerActionCode === "enableOnDemand") {
+    return "the included usage quota has been used up and on-demand usage is not enabled";
+  }
+  if (providerActionCode === "upgradePlan") {
+    return "the included usage quota for this mem9 account has been used up";
+  }
+  if (providerActionCode === "resolveAccountState") {
+    return "the current account or billing state blocks runtime memory access";
+  }
+  return "the runtime quota check blocked this request";
+}
+
+function quotaNoticeSubject(denied: RuntimeQuotaDenied, operation: string): { headline: string; userState: string } {
+  const meter = normalizeString(denied.meter);
+  if (meter === "memory_write_requests") {
+    return {
+      headline: "Mem9 memory saving is temporarily unavailable",
+      userState: "mem9 cannot save new memories right now",
+    };
+  }
+  if (meter === "memory_recall_requests") {
+    return {
+      headline: "Mem9 recall is temporarily unavailable",
+      userState: "mem9 cannot recall memories right now",
+    };
+  }
+
+  const operationText = normalizeString(operation).toLowerCase();
+  if (/\b(ingest|save|store|write)\b/.test(operationText)) {
+    return {
+      headline: "Mem9 memory saving is temporarily unavailable",
+      userState: "mem9 cannot save new memories right now",
+    };
+  }
+  if (/\b(recall|search)\b/.test(operationText)) {
+    return {
+      headline: "Mem9 recall is temporarily unavailable",
+      userState: "mem9 cannot recall memories right now",
+    };
+  }
+
+  return {
+    headline: "Mem9 memory is temporarily unavailable",
+    userState: "mem9 cannot complete the memory request right now",
+  };
+}
+
+function actionUrlForDenied(denied: RuntimeQuotaDenied): string {
+  return normalizeString(denied.recommendedAction?.url);
+}
+
+function actionInstruction(denied: RuntimeQuotaDenied): string {
+  const action = denied.recommendedAction;
+  const providerActionCode = normalizeString(action?.providerActionCode);
+  const actionUrl = actionUrlForDenied(denied);
+  if (!actionUrl) {
+    if (isPostQuotaRateLimited(denied)) {
+      return "Tell them that the quota/rate-limit check blocked this request and to retry later or open the mem9 console to review account and billing settings.";
+    }
+    return "Ask them to open the mem9 console to resolve the account or billing state.";
+  }
+
+  switch (providerActionCode) {
+    case "claimApiKey":
+      return `Ask them to open this link to sign in or create a mem9 account and claim this API key: ${actionUrl}. After claiming the key, they can upgrade their plan or set up billing to get more usage. Include the link exactly as written.`;
+    case "upgradePlan":
+      return `Ask them to open this link to upgrade their mem9 plan and get more included usage: ${actionUrl}. Include the link exactly as written.`;
+    case "increaseSpendingLimit":
+      return `Ask them to open this link to increase the mem9 spending limit or adjust billing settings: ${actionUrl}. Include the link exactly as written.`;
+    case "enableOnDemand":
+      return `Ask them to open this link to enable billing or on-demand usage for mem9: ${actionUrl}. Include the link exactly as written.`;
+    case "resolveAccountState":
+      return `Ask them to open this mem9 link to resolve the account or billing state: ${actionUrl}. Include the link exactly as written.`;
+    default:
+      return `Ask them to open this mem9 link to resolve the account or billing state: ${actionUrl}. Include the link exactly as written.`;
+  }
+}
+
+export function parseRuntimeQuotaDenied(value: unknown): RuntimeQuotaDenied | null {
+  const payload = value instanceof Mem9HttpError ? value.data : value;
+  if (!isRecord(payload)) {
+    return null;
+  }
+
+  const details = isRecord(payload.details) ? payload.details : {};
+  if (normalizeString(details.errorCategory) !== "runtime_quota_denied") {
+    return null;
+  }
+  const runtimeQuota = isRecord(details.runtimeQuota) ? details.runtimeQuota : {};
+
+  const recommendedAction = normalizeRecommendedAction(runtimeQuota);
+  const retryAfter = retryAfterSeconds(runtimeQuota);
+  const reason = quotaGateReason(runtimeQuota);
+  return {
+    status: value instanceof Mem9HttpError ? value.status : null,
+    code: "runtime_quota_denied",
+    message: normalizeString(payload.error) || "Runtime usage quota denied.",
+    ...(normalizeString(runtimeQuota.meter) ? { meter: normalizeString(runtimeQuota.meter) } : {}),
+    ...(reason ? { quotaGateReason: reason } : {}),
+    ...(retryAfter !== null ? { retryAfterSeconds: retryAfter } : {}),
+    ...(recommendedAction ? { recommendedAction } : {}),
+  };
+}
+
+export function formatRuntimeQuotaNotice(value: unknown, operation: string): string {
+  const denied = parseRuntimeQuotaDenied(value);
+  if (!denied) {
+    return "";
+  }
+
+  const subject = quotaNoticeSubject(denied, operation);
+  return `${subject.headline} because ${quotaReason(denied)}. In your reply, briefly tell the user that ${subject.userState}. ${actionInstruction(denied)}`;
+}
+
+export function toolErrorPayload(error: unknown): Record<string, unknown> {
+  const denied = parseRuntimeQuotaDenied(error);
+  if (denied) {
+    const actionUrl = actionUrlForDenied(denied);
+    return {
+      ok: false,
+      error: denied.message,
+      status_code: denied.status,
+      code: denied.code,
+      quota: {
+        code: denied.code,
+        message: denied.message,
+        ...(denied.retryAfterSeconds !== undefined ? { retryAfterSeconds: denied.retryAfterSeconds } : {}),
+        ...(denied.recommendedAction ? { recommendedAction: denied.recommendedAction } : {}),
+      },
+      ...(actionUrl ? { action_url: actionUrl } : {}),
+    };
+  }
+
+  return {
+    ok: false,
+    error: error instanceof Error ? error.message : String(error),
+  };
+}

package/src/server/server-backend.ts

@@ -12,10 +12,11 @@ import type {
   SearchInput,
 } from "../shared/types.ts";
 import { DEFAULT_SCOPE_CONFIG } from "../shared/defaults.ts";
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+import {
+  Mem9HttpError,
+  messageFromErrorBody,
+  parseJsonOrUndefined,
+} from "./quota-error.ts";
 
 function normalizeTimeoutMs(value: number | undefined, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
@@ -82,13 +83,16 @@ export class ServerBackend implements MemoryBackend {
     if (resp.status === 204) return undefined as T;
 
     const text = await resp.text();
-    const data = text ? (JSON.parse(text) as unknown) : undefined;
     if (!resp.ok) {
-      const message =
-        isRecord(data) && typeof data.error === "string" ? data.error : `HTTP ${resp.status}`;
-      throw new Error(message);
+      const data = parseJsonOrUndefined(text);
+      throw new Mem9HttpError(
+        messageFromErrorBody(resp.status, text, data),
+        resp.status,
+        text,
+        data,
+      );
     }
-    return data as T;
+    return JSON.parse(text) as T;
   }
 
   async store(input: CreateMemoryInput): Promise<StoreResult> {
@@ -133,7 +137,7 @@ export class ServerBackend implements MemoryBackend {
     try {
       return await this.request<Memory>("GET", this.memoryPath(`/memories/${id}`));
     } catch (err) {
-      if (err instanceof Error && (err.message.includes("not found") || err.message.includes("404"))) {
+      if (err instanceof Mem9HttpError && err.status === 404) {
         return null;
       }
       throw err;
@@ -144,7 +148,7 @@ export class ServerBackend implements MemoryBackend {
     try {
       return await this.request<Memory>("PUT", this.memoryPath(`/memories/${id}`), input);
     } catch (err) {
-      if (err instanceof Error && (err.message.includes("not found") || err.message.includes("404"))) {
+      if (err instanceof Mem9HttpError && err.status === 404) {
         return null;
       }
       throw err;
@@ -156,7 +160,7 @@ export class ServerBackend implements MemoryBackend {
       await this.request("DELETE", this.memoryPath(`/memories/${id}`));
       return true;
     } catch (err) {
-      if (err instanceof Error && (err.message.includes("not found") || err.message.includes("404"))) {
+      if (err instanceof Mem9HttpError && err.status === 404) {
         return false;
       }
       throw err;

package/src/server/tools.ts

@@ -5,6 +5,11 @@ import type {
   UpdateMemoryInput,
   SearchInput,
 } from "../shared/types.ts";
+import { toolErrorPayload } from "./quota-error.ts";
+
+function jsonToolError(error: unknown): string {
+  return JSON.stringify(toolErrorPayload(error));
+}
 
 /**
  * Build the 5 memory tools for OpenCode.
@@ -45,10 +50,7 @@ export function buildTools(backend: MemoryBackend): Record<string, ReturnType<ty
           const result = await backend.store(input);
           return JSON.stringify({ ok: true, data: result });
         } catch (err) {
-          return JSON.stringify({
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-          });
+          return jsonToolError(err);
         }
       },
     }),
@@ -97,10 +99,7 @@ export function buildTools(backend: MemoryBackend): Record<string, ReturnType<ty
           const result = await backend.search(input);
           return JSON.stringify({ ok: true, ...result });
         } catch (err) {
-          return JSON.stringify({
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-          });
+          return jsonToolError(err);
         }
       },
     }),
@@ -118,10 +117,7 @@ export function buildTools(backend: MemoryBackend): Record<string, ReturnType<ty
           }
           return JSON.stringify({ ok: true, data: result });
         } catch (err) {
-          return JSON.stringify({
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-          });
+          return jsonToolError(err);
         }
       },
     }),
@@ -157,10 +153,7 @@ export function buildTools(backend: MemoryBackend): Record<string, ReturnType<ty
           }
           return JSON.stringify({ ok: true, data: result });
         } catch (err) {
-          return JSON.stringify({
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-          });
+          return jsonToolError(err);
         }
       },
     }),
@@ -178,10 +171,7 @@ export function buildTools(backend: MemoryBackend): Record<string, ReturnType<ty
           }
           return JSON.stringify({ ok: true });
         } catch (err) {
-          return JSON.stringify({
-            ok: false,
-            error: err instanceof Error ? err.message : String(err),
-          });
+          return jsonToolError(err);
         }
       },
     }),