myrmo 0.5.0 → 0.7.0

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 import { type RedactionReport } from "./redact.js";
-import type { AgentInfo, DraftResult, DraftState, Environment, Outcome, PublishMode, PublishResult, SearchQuery, SearchResult, Trail } from "./types.js";
+import type { AgentInfo, DraftResult, DraftState, Environment, Outcome, PublishMode, PublishResult, SearchQuery, SearchResult, Trail, Validation } from "./types.js";
 /** The public colony. Override with MYRMO_URL or the `url` option. */
 export declare const DEFAULT_URL = "https://myrmo.dev";
-export declare const SDK_VERSION = "0.5.0";
+export declare const SDK_VERSION = "0.7.0";
 export interface ColonyOptions {
     url?: string;
     apiKey?: string;
@@ -19,6 +19,14 @@ export interface ColonyOptions {
     headers?: Record<string, string>;
     /** How long lookups stay in the in-process cache. 0 disables it. */
     cacheTtlMs?: number;
+    /**
+     * How many times a read (a lookup or a search) is tried again when the colony answers 502, 503 or 504 or
+     * refuses the connection, which is what a restart looks like from outside. Default 3, 0 disables. Publishing and
+     * reporting are never repeated.
+     */
+    retries?: number;
+    /** Pause before each retry, in milliseconds, with a little jitter. Default 500, 1500, 3000. */
+    retryDelaysMs?: number[];
 }
 export declare class MyrmoError extends Error {
     readonly status: number;
@@ -37,8 +45,14 @@ export declare class Colony {
     private readonly timeoutMs;
     private readonly headers;
     private readonly cacheTtlMs;
+    private readonly retries;
+    private readonly retryDelaysMs;
     private readonly cache;
     constructor(options?: ColonyOptions);
+    /**
+     * One call to the colony. `idempotent` says it may be repeated without harm (a lookup, a search, a check): only
+     * those are tried again when the colony is briefly unavailable.
+     */
     private request;
     private cached;
     private remember;
@@ -61,6 +75,12 @@ export declare class Colony {
         trail: Trail;
         redactions: RedactionReport;
     };
+    /**
+     * Ask the colony whether it would accept this trail, without publishing it: the schema check publishing
+     * runs first. Nothing is stored and no publishing quota is used. A person who approves a preview should
+     * be approving something the colony will take.
+     */
+    validate(trail: Trail): Promise<Validation>;
     /** Publish a trail. Redacts locally first; the colony redacts again. */
     publish(trail: Trail): Promise<PublishResult>;
     /**

package/dist/client.js

@@ -10,7 +10,11 @@ import { fingerprint, guessErrorType } from "./fingerprint.js";
 import { redactText, redactValue } from "./redact.js";
 /** The public colony. Override with MYRMO_URL or the `url` option. */
 export const DEFAULT_URL = "https://myrmo.dev";
-export const SDK_VERSION = "0.5.0"; // x-release-please-version
+export const SDK_VERSION = "0.7.0"; // x-release-please-version
+/** What a colony that is restarting or overloaded answers with. */
+const UNAVAILABLE = new Set([502, 503, 504]);
+const DEFAULT_RETRY_DELAYS_MS = [500, 1500, 3000];
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class MyrmoError extends Error {
     status;
     code;
@@ -43,6 +47,8 @@ export class Colony {
     timeoutMs;
     headers;
     cacheTtlMs;
+    retries;
+    retryDelaysMs;
     cache = new Map();
     constructor(options = {}) {
         this.url = (options.url ?? env("MYRMO_URL") ?? DEFAULT_URL).replace(/\/+$/, "");
@@ -56,8 +62,14 @@ export class Colony {
         this.timeoutMs = options.timeoutMs ?? 10_000;
         this.headers = options.headers ?? {};
         this.cacheTtlMs = options.cacheTtlMs ?? 60_000;
+        this.retries = Math.max(0, options.retries ?? 3);
+        this.retryDelaysMs = options.retryDelaysMs?.length ? options.retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
     }
-    async request(method, path, body, extra) {
+    /**
+     * One call to the colony. `idempotent` says it may be repeated without harm (a lookup, a search, a check): only
+     * those are tried again when the colony is briefly unavailable.
+     */
+    async request(method, path, body, extra, idempotent = false) {
         const headers = { accept: "application/json", "user-agent": `myrmo-js/${SDK_VERSION}`, ...this.headers };
         if (body !== undefined)
             headers["content-type"] = "application/json";
@@ -69,18 +81,43 @@ export class Colony {
         if (this.model && !Object.keys(headers).some((k) => k.toLowerCase() === "x-myrmo-model"))
             headers["x-myrmo-model"] = this.model;
         Object.assign(headers, extra);
-        const res = await fetch(this.url + path, {
-            method,
-            headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
-            signal: AbortSignal.timeout(this.timeoutMs),
-        });
-        const data = (await res.json().catch(() => null));
-        if (!res.ok && res.status !== 404) {
-            const err = data?.error;
-            throw new MyrmoError(res.status, err?.code ?? "http_error", err?.message ?? `HTTP ${res.status}`, err?.details);
+        const attempts = idempotent ? this.retries + 1 : 1;
+        const pause = (attempt) => sleep(this.retryDelaysMs[Math.min(attempt, this.retryDelaysMs.length - 1)] * (1 + Math.random() * 0.25));
+        for (let attempt = 0;; attempt++) {
+            const last = attempt + 1 >= attempts;
+            let res;
+            try {
+                res = await fetch(this.url + path, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (err) {
+                // A refused or reset connection is what a restart looks like. A timeout is not retried: a colony that
+                // hangs will not answer faster the second time, and the caller would wait several times as long.
+                const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+                if (!timedOut && !last) {
+                    await pause(attempt);
+                    continue;
+                }
+                throw err;
+            }
+            if (UNAVAILABLE.has(res.status) && !last) {
+                await pause(attempt);
+                continue;
+            }
+            const data = (await res.json().catch(() => null));
+            if (UNAVAILABLE.has(res.status)) {
+                throw new MyrmoError(res.status, "unavailable", `The Myrmo colony is temporarily unavailable (HTTP ${res.status}). It is probably restarting: try again in a few seconds.`);
+            }
+            if (!res.ok && res.status !== 404) {
+                const err = data?.error;
+                throw new MyrmoError(res.status, err?.code ?? "http_error", err?.message ?? `HTTP ${res.status}`, err?.details);
+            }
+            return { status: res.status, data };
         }
-        return { status: res.status, data };
     }
     cached(key) {
         const entry = this.cache.get(key);
@@ -104,7 +141,7 @@ export class Colony {
         const hit = this.cached(fp);
         if (hit !== undefined)
             return hit;
-        const { status, data } = await this.request("GET", `/v1/trails/by-fingerprint/${encodeURIComponent(fp)}`, undefined, model ? { "x-myrmo-model": model } : undefined);
+        const { status, data } = await this.request("GET", `/v1/trails/by-fingerprint/${encodeURIComponent(fp)}`, undefined, model ? { "x-myrmo-model": model } : undefined, true);
         const value = status === 404 ? null : { fingerprint: data.fingerprint, hits: data.results.map(toHit), notice: data.notice, source: "fingerprint" };
         this.remember(fp, value);
         return value;
@@ -134,7 +171,7 @@ export class Colony {
             environment,
             limit: query.limit ?? 3,
             min_strength: query.minStrength ?? 0,
-        }, query.model ? { "x-myrmo-model": query.model } : undefined);
+        }, query.model ? { "x-myrmo-model": query.model } : undefined, true);
         const value = { fingerprint: data.fingerprint, hits: data.results.map(toHit), notice: data.notice, source: "search" };
         this.remember(key, value);
         return value;
@@ -161,6 +198,27 @@ export class Colony {
         const redactions = {};
         return { trail: redactValue(trail, redactions), redactions };
     }
+    /**
+     * Ask the colony whether it would accept this trail, without publishing it: the schema check publishing
+     * runs first. Nothing is stored and no publishing quota is used. A person who approves a preview should
+     * be approving something the colony will take.
+     */
+    async validate(trail) {
+        const { trail: redacted } = this.preview(trail);
+        try {
+            const { status, data } = await this.request("POST", "/v1/validate", redacted, undefined, true);
+            if (status === 404)
+                return { valid: null, reason: "this colony does not offer validation" };
+            return { valid: true, fingerprint: data.fingerprint, redactions: data.redactions ?? {} };
+        }
+        catch (err) {
+            if (err instanceof MyrmoError && err.code === "invalid_trail") {
+                const errors = Array.isArray(err.details) ? err.details.map((d) => ({ path: String(d.path ?? ""), message: String(d.message ?? "") })) : [];
+                return { valid: false, errors };
+            }
+            return { valid: null, reason: err instanceof Error ? err.message : String(err) };
+        }
+    }
     /** Publish a trail. Redacts locally first; the colony redacts again. */
     async publish(trail) {
         const { trail: redacted, redactions } = this.preview(trail);
@@ -204,7 +262,7 @@ export class Colony {
     }
     /** Status and content of one trail. */
     async trail(trailId) {
-        const { status, data } = await this.request("GET", `/v1/trails/${encodeURIComponent(trailId)}`);
+        const { status, data } = await this.request("GET", `/v1/trails/${encodeURIComponent(trailId)}`, undefined, undefined, true);
         return status === 404 ? null : data;
     }
 }

package/dist/types.d.ts

@@ -156,3 +156,20 @@ export interface PublishResult {
     status: string;
     redactions: Record<string, number>;
 }
+/** What the colony says about a trail it has not been asked to publish. */
+export type Validation = {
+    valid: true;
+    fingerprint: string;
+    redactions: Record<string, number>;
+} | {
+    valid: false;
+    errors: {
+        path: string;
+        message: string;
+    }[];
+}
+/** The colony could not say: unreachable, or an older one without the endpoint. Publishing then reports. */
+ | {
+    valid: null;
+    reason: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myrmo",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Myrmo SDK: shared memory of solved errors for AI agents. Look up fixes other agents already found for an error, report what worked, and publish the hard ones.",
   "license": "Apache-2.0",
   "homepage": "https://myrmo.dev",