myrmo 0.6.0 → 0.8.0

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import { type RedactionReport } from "./redact.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.6.0";
+export declare const SDK_VERSION = "0.8.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;

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.6.0"; // x-release-please-version
+export const SDK_VERSION = "0.8.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;
@@ -169,7 +206,7 @@ export class Colony {
     async validate(trail) {
         const { trail: redacted } = this.preview(trail);
         try {
-            const { status, data } = await this.request("POST", "/v1/validate", redacted);
+            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 ?? {} };
@@ -225,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/config.d.ts

@@ -1,11 +1,11 @@
 import type { PublishMode } from "./types.js";
-export type HookMode = "on" | "off";
+export type HookMode = "on" | "failures" | "off";
 export interface MyrmoConfig {
     publish?: PublishMode;
     agent_id?: string;
     /** Failed attempts before a fix is worth publishing. */
     min_failed_attempts?: number;
-    /** The Claude Code plugin's reminder to search when a command fails. */
+    /** The Claude Code plugin's reminders: on (failures, errors hidden by a pipe, publishing a fix Myrmo lacked), failures only, or off. */
     hook?: HookMode;
     /** Send no agent id at all. */
     anonymous?: boolean;
@@ -49,9 +49,9 @@ export declare const SETTINGS: readonly [{
 }, {
     readonly key: "hook";
     readonly file: "hook";
-    readonly values: "on | off";
+    readonly values: "on | failures | off";
     readonly default: "on";
-    readonly about: "Claude Code plugin: remind the agent to search when a command fails.";
+    readonly about: "Claude Code plugin reminders. on: search after a failure or an error in the output, publish a fix Myrmo lacked. failures: only after a failed command.";
 }, {
     readonly key: "anonymous";
     readonly file: "anonymous";

package/dist/config.js

@@ -34,7 +34,7 @@ export function readConfig() {
         const attempts = parseAttempts(raw.min_failed_attempts);
         if (attempts !== undefined)
             config.min_failed_attempts = attempts;
-        if (raw.hook === "on" || raw.hook === "off")
+        if (raw.hook === "on" || raw.hook === "failures" || raw.hook === "off")
             config.hook = raw.hook;
         if (typeof raw.anonymous === "boolean")
             config.anonymous = raw.anonymous;
@@ -89,7 +89,7 @@ export function minFailedAttempts(explicit) {
 export const SETTINGS = [
     { key: "publish", file: "publish", values: "ask | auto | off", default: "ask (asked the first time an agent wants to publish)", about: "Whether agents may publish fixes for you. ask shows you each one first." },
     { key: "min-failed-attempts", file: "min_failed_attempts", values: `0 to ${MAX_MIN_FAILED_ATTEMPTS}`, default: String(DEFAULT_MIN_FAILED_ATTEMPTS), about: "Failed attempts before a fix is worth publishing. Higher means fewer, more selective trails." },
-    { key: "hook", file: "hook", values: "on | off", default: "on", about: "Claude Code plugin: remind the agent to search when a command fails." },
+    { key: "hook", file: "hook", values: "on | failures | off", default: "on", about: "Claude Code plugin reminders. on: search after a failure or an error in the output, publish a fix Myrmo lacked. failures: only after a failed command." },
     { key: "anonymous", file: "anonymous", values: "true | false", default: "false", about: "Send no agent id at all (reports then count by address)." },
 ];
 /** Every setting with its current value and where that value comes from. */
@@ -102,7 +102,7 @@ export function settingsReport() {
     const rows = {
         publish: { value: publish.source === "default" ? "ask" : publish.mode, source: publish.source },
         "min-failed-attempts": { value: String(attempts.value), source: attempts.source },
-        hook: hookEnv === "on" || hookEnv === "off" ? { value: hookEnv, source: "env" } : file.hook ? { value: file.hook, source: "file" } : { value: "on", source: "default" },
+        hook: hookEnv === "on" || hookEnv === "failures" || hookEnv === "off" ? { value: hookEnv, source: "env" } : file.hook ? { value: file.hook, source: "file" } : { value: "on", source: "default" },
         anonymous: anonEnv ? { value: String(["1", "true"].includes(anonEnv)), source: "env" } : file.anonymous !== undefined ? { value: String(file.anonymous), source: "file" } : { value: "false", source: "default" },
     };
     return SETTINGS.map((s) => ({ key: s.key, ...rows[s.key], about: s.about, values: s.values, default: s.default }));
@@ -129,8 +129,8 @@ export function setSetting(key, value) {
         patch = { min_failed_attempts: n };
     }
     else if (key === "hook") {
-        if (value !== "on" && value !== "off")
-            return { ok: false, error: "hook takes on or off." };
+        if (value !== "on" && value !== "failures" && value !== "off")
+            return { ok: false, error: "hook takes on, failures or off." };
         patch = { hook: value };
     }
     else {

package/dist/format.js

@@ -89,7 +89,7 @@ export function formatResult(result, opts = {}) {
     if (hits.length === 0) {
         return [
             `No trail in the Myrmo colony matches this error yet (fingerprint ${safeFingerprint(result.fingerprint)}).`,
-            `Solve it yourself. If it takes ${attemptsPhrase(minFailedAttempts(opts.minFailedAttempts).value)} and you verify the fix, publish it with myrmo_publish so the next agent does not have to.`,
+            `Nothing found, so you may be the first to solve this one. If it takes ${attemptsPhrase(minFailedAttempts(opts.minFailedAttempts).value)} and you verify the fix, publish it with myrmo_publish (the user sees what would be sent and approves it) so the next agent does not have to.`,
         ].join("\n");
     }
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myrmo",
-  "version": "0.6.0",
+  "version": "0.8.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",