mindgraph 0.15.1 → 0.17.0

package/dist/index.js

@@ -25,16 +25,120 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/retry.ts
+var READ_POSTS = /* @__PURE__ */ new Set([
+  "/search",
+  "/retrieve/context",
+  "/nodes/batch",
+  "/edges/batch",
+  "/subgraph",
+  "/embeddings/search",
+  "/embeddings/search-text",
+  "/ontology/query",
+  "/ontology/query/structured",
+  "/ontology/objects/search"
+]);
+var READ_ACTIONS = {
+  "/retrieve": [
+    "text",
+    "semantic",
+    "hybrid",
+    "active_goals",
+    "open_questions",
+    "preferences",
+    "weak_claims",
+    "pending_approvals",
+    "unresolved_contradictions",
+    "merge_candidates",
+    "stale_derivations",
+    "curation_counts",
+    "layer",
+    "recent"
+  ],
+  "/traverse": ["chain", "top_k_paths", "neighborhood", "path", "subgraph"],
+  "/reality/series": ["window", "aggregate", "latest", "list_for_entity", "batch_latest", "batch_aggregate"],
+  "/intent/deliberation": ["get_open"],
+  "/action/risk": ["get_assessments"],
+  "/action/skill": ["get", "list"],
+  "/memory/config": ["get_preferences", "get_policies"],
+  "/memory/sync": ["status"],
+  "/agent/plan": ["get_plan", "resume_work"],
+  "/agent/governance": ["get_pending", "check"],
+  "/agent/execution": ["get_executions"],
+  "/evolve": ["history", "snapshot"]
+};
+var IDEMPOTENT_WORK = /* @__PURE__ */ new Set([
+  "claim_task",
+  "heartbeat",
+  "start_iteration",
+  "checkpoint_iteration",
+  "block_task",
+  "complete_task",
+  "abandon_iteration"
+]);
+function errorFields(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const fields = body;
+  return {
+    ...typeof fields.code === "string" ? { code: fields.code } : {},
+    ...typeof fields.retriable === "boolean" ? { retriable: fields.retriable } : {}
+  };
+}
+function canRetryRequest(method, path, body) {
+  if (method === "GET" || method === "HEAD") return true;
+  if (method !== "POST") return false;
+  if (READ_POSTS.has(path)) return true;
+  const fields = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  if (typeof fields.action !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(READ_ACTIONS, path) && READ_ACTIONS[path].includes(fields.action)) return true;
+  return path === "/agent/plan" && IDEMPOTENT_WORK.has(fields.action) && typeof fields.idempotency_key === "string" && fields.idempotency_key.trim().length > 0;
+}
+function permitsRetry(fields) {
+  return fields.retriable !== false && ![
+    "query_memory_budget_exceeded",
+    "query_timeout",
+    "query_cancelled",
+    "vector_index_rebuilding"
+  ].includes(fields.code ?? "");
+}
+function retryDelayMs(header, backoff, attempt) {
+  const hint = Number(header);
+  return Number.isFinite(hint) && hint > 0 ? Math.min(hint * 1e3, 1e4) : Math.min(backoff * 2 ** Math.min(attempt, 32), 1e4);
+}
+
 // src/client.ts
 function seg(value) {
   return encodeURIComponent(String(value));
 }
+function pathSteps(response) {
+  const wrapped = response && typeof response === "object" && !Array.isArray(response) ? response : void 0;
+  const raw = wrapped?.steps ?? response;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    const step = value;
+    const taggedName = (tagged) => {
+      if (typeof tagged === "string") return tagged;
+      if (!tagged || typeof tagged !== "object" || Array.isArray(tagged)) return null;
+      const custom = tagged.Custom;
+      return typeof custom === "string" ? custom : null;
+    };
+    return [{
+      ...step,
+      node_type: taggedName(step.node_type) ?? "Unknown",
+      edge_type: taggedName(step.edge_type)
+    }];
+  });
+}
 var MindGraphError = class extends Error {
   constructor(message, status, body) {
     super(message);
     this.status = status;
     this.body = body;
     this.name = "MindGraphError";
+    const fields = errorFields(body);
+    this.code = fields.code;
+    this.retriable = fields.retriable;
   }
 };
 var MindGraph = class {
@@ -52,6 +156,18 @@ var MindGraph = class {
     this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new RangeError("maxRetries must be a non-negative safe integer");
+    }
+    if (!Number.isFinite(this.retryBackoffMs) || this.retryBackoffMs < 0) {
+      throw new RangeError("retryBackoffMs must be finite and non-negative");
+    }
+    if (config.timeoutMs !== void 0) {
+      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+      }
+      this.timeoutMs = config.timeoutMs;
+    }
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -68,9 +184,14 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
+    const retrySafe = canRetryRequest(
+      method,
+      path,
+      typeof init.body === "string" ? JSON.parse(init.body) : void 0
+    );
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const res = await fetch(url, init);
+      const res = await this.fetchWithDeadline(url, init, method, path);
       if (!res.ok) {
         const text2 = await res.text().catch(() => "");
         let parsed;
@@ -84,10 +205,9 @@ var MindGraph = class {
           res.status,
           parsed
         );
-        if (res.status === 503 && attempt < this.maxRetries) {
+        if (res.status === 503 && retrySafe && permitsRetry(err) && attempt < this.maxRetries) {
           lastError = err;
-          const retryAfterSecs = Number(res.headers.get("retry-after"));
-          const delay = Number.isFinite(retryAfterSecs) && retryAfterSecs > 0 ? Math.min(retryAfterSecs * 1e3, 1e4) : this.retryBackoffMs * 2 ** attempt;
+          const delay = retryDelayMs(res.headers.get("retry-after"), this.retryBackoffMs, attempt);
           await new Promise((r) => setTimeout(r, delay));
           continue;
         }
@@ -99,6 +219,33 @@ var MindGraph = class {
     }
     throw lastError;
   }
+  /**
+   * One HTTP attempt. With `timeoutMs` set, the attempt is aborted at the
+   * deadline and surfaces as a non-retriable `MindGraphError` (`code:
+   * "timeout"`, `status: 0`). Without it the request is sent unchanged — no
+   * AbortSignal is attached, preserving the pre-0.16 behaviour.
+   */
+  async fetchWithDeadline(url, init, method, path) {
+    if (this.timeoutMs === void 0) {
+      return fetch(url, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new MindGraphError(
+          `${method} ${path} timed out after ${this.timeoutMs}ms`,
+          0,
+          { error: "timeout", code: "timeout", retriable: false }
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   get(path) {
     return this.request("GET", path);
   }
@@ -348,6 +495,40 @@ var MindGraph = class {
   async memorySync(req) {
     return this.post("/memory/sync", req);
   }
+  // ---- Memory (fast path) ----
+  /**
+   * Store a small piece of text as a memory, synchronously. The node is
+   * BM25- and vector-searchable when this resolves (`searchable` says which).
+   * Pass `custom_id` to make re-sends an upsert of the same node.
+   */
+  async remember(text, options = {}) {
+    return this.post("/memory/remember", { text, ...options });
+  }
+  /**
+   * Reversibly remove a memory by `uid` or `custom_id` (tombstone plus its
+   * connected edges). `dry_run: true` previews the affected edge uids first.
+   * Undo with `restore(uid)` and `evolve({ action: "restore_edge", uid })`.
+   */
+  async forget(target, options = {}) {
+    return this.post("/memory/forget", { ...target, ...options });
+  }
+  /**
+   * Operator guidance for what agents should remember into a Space; surfaced
+   * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+   */
+  async setRememberInstructions(text, options = {}) {
+    return this.post("/memory/config", {
+      action: "set_remember_instructions",
+      text,
+      ...options
+    });
+  }
+  async getRememberInstructions(options = {}) {
+    return this.post("/memory/config", {
+      action: "get_remember_instructions",
+      ...options
+    });
+  }
   // ---- Agent Layer ----
   async plan(req) {
     return this.post("/agent/plan", req);
@@ -570,7 +751,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async neighborhood(uid, maxDepth = 1) {
     const r = await this.post("/traverse", {
@@ -578,7 +759,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async subgraph(uid, opts) {
     return this.post("/subgraph", { start_uids: [uid], ...opts });

package/dist/index.mjs

@@ -1,13 +1,117 @@
+// src/retry.ts
+var READ_POSTS = /* @__PURE__ */ new Set([
+  "/search",
+  "/retrieve/context",
+  "/nodes/batch",
+  "/edges/batch",
+  "/subgraph",
+  "/embeddings/search",
+  "/embeddings/search-text",
+  "/ontology/query",
+  "/ontology/query/structured",
+  "/ontology/objects/search"
+]);
+var READ_ACTIONS = {
+  "/retrieve": [
+    "text",
+    "semantic",
+    "hybrid",
+    "active_goals",
+    "open_questions",
+    "preferences",
+    "weak_claims",
+    "pending_approvals",
+    "unresolved_contradictions",
+    "merge_candidates",
+    "stale_derivations",
+    "curation_counts",
+    "layer",
+    "recent"
+  ],
+  "/traverse": ["chain", "top_k_paths", "neighborhood", "path", "subgraph"],
+  "/reality/series": ["window", "aggregate", "latest", "list_for_entity", "batch_latest", "batch_aggregate"],
+  "/intent/deliberation": ["get_open"],
+  "/action/risk": ["get_assessments"],
+  "/action/skill": ["get", "list"],
+  "/memory/config": ["get_preferences", "get_policies"],
+  "/memory/sync": ["status"],
+  "/agent/plan": ["get_plan", "resume_work"],
+  "/agent/governance": ["get_pending", "check"],
+  "/agent/execution": ["get_executions"],
+  "/evolve": ["history", "snapshot"]
+};
+var IDEMPOTENT_WORK = /* @__PURE__ */ new Set([
+  "claim_task",
+  "heartbeat",
+  "start_iteration",
+  "checkpoint_iteration",
+  "block_task",
+  "complete_task",
+  "abandon_iteration"
+]);
+function errorFields(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const fields = body;
+  return {
+    ...typeof fields.code === "string" ? { code: fields.code } : {},
+    ...typeof fields.retriable === "boolean" ? { retriable: fields.retriable } : {}
+  };
+}
+function canRetryRequest(method, path, body) {
+  if (method === "GET" || method === "HEAD") return true;
+  if (method !== "POST") return false;
+  if (READ_POSTS.has(path)) return true;
+  const fields = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  if (typeof fields.action !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(READ_ACTIONS, path) && READ_ACTIONS[path].includes(fields.action)) return true;
+  return path === "/agent/plan" && IDEMPOTENT_WORK.has(fields.action) && typeof fields.idempotency_key === "string" && fields.idempotency_key.trim().length > 0;
+}
+function permitsRetry(fields) {
+  return fields.retriable !== false && ![
+    "query_memory_budget_exceeded",
+    "query_timeout",
+    "query_cancelled",
+    "vector_index_rebuilding"
+  ].includes(fields.code ?? "");
+}
+function retryDelayMs(header, backoff, attempt) {
+  const hint = Number(header);
+  return Number.isFinite(hint) && hint > 0 ? Math.min(hint * 1e3, 1e4) : Math.min(backoff * 2 ** Math.min(attempt, 32), 1e4);
+}
+
 // src/client.ts
 function seg(value) {
   return encodeURIComponent(String(value));
 }
+function pathSteps(response) {
+  const wrapped = response && typeof response === "object" && !Array.isArray(response) ? response : void 0;
+  const raw = wrapped?.steps ?? response;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    const step = value;
+    const taggedName = (tagged) => {
+      if (typeof tagged === "string") return tagged;
+      if (!tagged || typeof tagged !== "object" || Array.isArray(tagged)) return null;
+      const custom = tagged.Custom;
+      return typeof custom === "string" ? custom : null;
+    };
+    return [{
+      ...step,
+      node_type: taggedName(step.node_type) ?? "Unknown",
+      edge_type: taggedName(step.edge_type)
+    }];
+  });
+}
 var MindGraphError = class extends Error {
   constructor(message, status, body) {
     super(message);
     this.status = status;
     this.body = body;
     this.name = "MindGraphError";
+    const fields = errorFields(body);
+    this.code = fields.code;
+    this.retriable = fields.retriable;
   }
 };
 var MindGraph = class {
@@ -25,6 +129,18 @@ var MindGraph = class {
     this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new RangeError("maxRetries must be a non-negative safe integer");
+    }
+    if (!Number.isFinite(this.retryBackoffMs) || this.retryBackoffMs < 0) {
+      throw new RangeError("retryBackoffMs must be finite and non-negative");
+    }
+    if (config.timeoutMs !== void 0) {
+      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+      }
+      this.timeoutMs = config.timeoutMs;
+    }
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -41,9 +157,14 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
+    const retrySafe = canRetryRequest(
+      method,
+      path,
+      typeof init.body === "string" ? JSON.parse(init.body) : void 0
+    );
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const res = await fetch(url, init);
+      const res = await this.fetchWithDeadline(url, init, method, path);
       if (!res.ok) {
         const text2 = await res.text().catch(() => "");
         let parsed;
@@ -57,10 +178,9 @@ var MindGraph = class {
           res.status,
           parsed
         );
-        if (res.status === 503 && attempt < this.maxRetries) {
+        if (res.status === 503 && retrySafe && permitsRetry(err) && attempt < this.maxRetries) {
           lastError = err;
-          const retryAfterSecs = Number(res.headers.get("retry-after"));
-          const delay = Number.isFinite(retryAfterSecs) && retryAfterSecs > 0 ? Math.min(retryAfterSecs * 1e3, 1e4) : this.retryBackoffMs * 2 ** attempt;
+          const delay = retryDelayMs(res.headers.get("retry-after"), this.retryBackoffMs, attempt);
           await new Promise((r) => setTimeout(r, delay));
           continue;
         }
@@ -72,6 +192,33 @@ var MindGraph = class {
     }
     throw lastError;
   }
+  /**
+   * One HTTP attempt. With `timeoutMs` set, the attempt is aborted at the
+   * deadline and surfaces as a non-retriable `MindGraphError` (`code:
+   * "timeout"`, `status: 0`). Without it the request is sent unchanged — no
+   * AbortSignal is attached, preserving the pre-0.16 behaviour.
+   */
+  async fetchWithDeadline(url, init, method, path) {
+    if (this.timeoutMs === void 0) {
+      return fetch(url, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new MindGraphError(
+          `${method} ${path} timed out after ${this.timeoutMs}ms`,
+          0,
+          { error: "timeout", code: "timeout", retriable: false }
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   get(path) {
     return this.request("GET", path);
   }
@@ -321,6 +468,40 @@ var MindGraph = class {
   async memorySync(req) {
     return this.post("/memory/sync", req);
   }
+  // ---- Memory (fast path) ----
+  /**
+   * Store a small piece of text as a memory, synchronously. The node is
+   * BM25- and vector-searchable when this resolves (`searchable` says which).
+   * Pass `custom_id` to make re-sends an upsert of the same node.
+   */
+  async remember(text, options = {}) {
+    return this.post("/memory/remember", { text, ...options });
+  }
+  /**
+   * Reversibly remove a memory by `uid` or `custom_id` (tombstone plus its
+   * connected edges). `dry_run: true` previews the affected edge uids first.
+   * Undo with `restore(uid)` and `evolve({ action: "restore_edge", uid })`.
+   */
+  async forget(target, options = {}) {
+    return this.post("/memory/forget", { ...target, ...options });
+  }
+  /**
+   * Operator guidance for what agents should remember into a Space; surfaced
+   * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+   */
+  async setRememberInstructions(text, options = {}) {
+    return this.post("/memory/config", {
+      action: "set_remember_instructions",
+      text,
+      ...options
+    });
+  }
+  async getRememberInstructions(options = {}) {
+    return this.post("/memory/config", {
+      action: "get_remember_instructions",
+      ...options
+    });
+  }
   // ---- Agent Layer ----
   async plan(req) {
     return this.post("/agent/plan", req);
@@ -543,7 +724,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async neighborhood(uid, maxDepth = 1) {
     const r = await this.post("/traverse", {
@@ -551,7 +732,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async subgraph(uid, opts) {
     return this.post("/subgraph", { start_uids: [uid], ...opts });

package/package.json

@@ -1,20 +1,33 @@
 {
   "name": "mindgraph",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "prepare": "npm run build",
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc --noEmit",
     "test": "vitest run",
     "test:offline": "vitest run src/offline.test.ts",
     "test:e2e": "vitest run src/integration.test.ts"
   },
-  "keywords": ["mindgraph", "knowledge-graph", "cognitive", "ai", "agent"],
+  "keywords": [
+    "mindgraph",
+    "knowledge-graph",
+    "cognitive",
+    "ai",
+    "agent"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuruheel/mindgraph-ts.git"
+  },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "tsup": "^8.0.0",