myrmo 0.7.0 → 0.9.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.7.0";
+export declare const SDK_VERSION = "0.9.0";
 export interface ColonyOptions {
     url?: string;
     apiKey?: string;

package/dist/client.js

@@ -6,11 +6,11 @@
 //   3. POST /v1/search (embedding + vector search; only for errors the colony has not fingerprinted)
 import { agentIdentity, publishChoice } from "./config.js";
 import { detectEnvironment, parsePackage } from "./environment.js";
-import { fingerprint, guessErrorType } from "./fingerprint.js";
+import { fingerprint2, 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.7.0"; // x-release-please-version
+export const SDK_VERSION = "0.9.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];
@@ -141,8 +141,18 @@ 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, true);
-        const value = status === 404 ? null : { fingerprint: data.fingerprint, hits: data.results.map(toHit), notice: data.notice, source: "fingerprint" };
+        let found;
+        try {
+            found = await this.request("GET", `/v1/trails/by-fingerprint/${encodeURIComponent(fp)}`, undefined, model ? { "x-myrmo-model": model } : undefined, true);
+        }
+        catch (err) {
+            // 400: a colony that predates fp2 does not know the key. Nothing exact to offer; the search that follows still finds the trail.
+            if (err instanceof MyrmoError && err.status === 400)
+                found = null;
+            else
+                throw err;
+        }
+        const value = found === null || found.status === 404 ? null : { fingerprint: found.data.fingerprint, hits: found.data.results.map(toHit), notice: found.data.notice, source: "fingerprint" };
         this.remember(fp, value);
         return value;
     }
@@ -150,7 +160,7 @@ export class Colony {
     async search(query) {
         const error = redactText(query.error);
         const errorType = query.errorType ?? guessErrorType(error);
-        const fp = fingerprint(query.runtime ?? "", errorType, error);
+        const fp = fingerprint2(error);
         const exact = await this.lookup(fp, query.model);
         if (exact && exact.hits.length > 0)
             return exact;

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/fingerprint.d.ts

@@ -1,6 +1,17 @@
 export declare const PREFIX = "fp1_";
+export declare const PREFIX_2 = "fp2_";
 /** Strip everything that varies between machines but not between errors. */
 export declare function normalizeMessage(errorType: string, message: string): string;
+/** Drop the leading exception classes, severity words and tool codes of an error line. */
+export declare function stripLabels(message: string): string;
+/** fp2: strip everything that varies between machines or between wrappers, but not between errors. */
+export declare function normalizeMessage2(message: string): string;
+/**
+ * The fingerprint the colony indexes: a hash of the error message alone. The key a trail is filed under is the one
+ * a searcher computes from the line it holds.
+ */
+export declare function fingerprint2(message: string): string;
+/** fp1, the retired fingerprint: the colony no longer indexes it. Use `fingerprint2`. */
 export declare function fingerprint(runtime: string, errorType: string, message: string): string;
 /** `Type: message` → `Type`, for callers that only have the error line. */
 export declare function guessErrorType(errorLine: string): string;

package/dist/fingerprint.js

@@ -1,7 +1,11 @@
-// Error fingerprint v1, a port of protocol/fingerprint_v1.py. The shared vectors in
-// protocol/fingerprint.v1.vectors.json are normative; see test/fingerprint.test.mjs.
+// Error fingerprints. `fingerprint2` (fp2, the one the colony indexes) is a port of protocol/fingerprint_v2.py: a hash of
+// the message alone, with the labels that wrap an error line dropped, because a searcher knows the line it holds and
+// nothing reliable about the error type a trail's author declared. `fingerprint` (fp1: runtime, type and message) is
+// the retired one, a port of protocol/fingerprint_v1.py. The shared vectors in protocol/fingerprint.v1.vectors.json and
+// protocol/fingerprint.v2.vectors.json are normative; see test/fingerprint.test.mjs.
 import { createHash } from "node:crypto";
 export const PREFIX = "fp1_";
+export const PREFIX_2 = "fp2_";
 const MAX_NORMALIZED_CHARS = 300;
 const SEPARATOR = "\u001f";
 const rule = (pattern, replacement) => [new RegExp(pattern, "g"), replacement];
@@ -31,6 +35,41 @@ export function normalizeMessage(errorType, message) {
         text = text.replace(pattern, replacement);
     return Array.from(text.replace(/\s+/g, " ").trim()).slice(0, MAX_NORMALIZED_CHARS).join("");
 }
+// Labels removed from the start of the message, one after another, at most MAX_LABELS of them. Matched on the text as
+// written (before lowercasing): the capital letter is what tells a class name from a word. Exactly the pattern of
+// protocol/fingerprint_v2.py.
+const MAX_LABELS = 4;
+const CLASS = String.raw `(?:[A-Za-z_][A-Za-z0-9_$]*\.)*[A-Z][A-Za-z0-9_$]*(?:Error|Exception|Warning|Failure)`;
+const SEVERITY = String.raw `(?:Error|ERROR|error|Fatal|FATAL|fatal|Warning|WARNING|warning|Panic|PANIC|panic|Exception|EXCEPTION|exception|Err|ERR|Caused by)` +
+    String.raw `(?:\[[A-Za-z0-9_]+\])?`;
+const TOOL_CODE = String.raw `(?:error|warning)\s+[A-Z]{1,5}[0-9]{2,5}`; // "error TS2322", "warning CS0168"
+const LABEL = new RegExp(String.raw `^(?:(?:Uncaught\s+)?(?:${CLASS}|${SEVERITY}|${TOOL_CODE})\s*:\s+|npm\s+(?:ERR!|error)\s+)`);
+/** Drop the leading exception classes, severity words and tool codes of an error line. */
+export function stripLabels(message) {
+    let text = message;
+    for (let i = 0; i < MAX_LABELS; i++) {
+        const shorter = text.replace(LABEL, "");
+        if (shorter === text)
+            break;
+        text = shorter;
+    }
+    return text;
+}
+/** fp2: strip everything that varies between machines or between wrappers, but not between errors. */
+export function normalizeMessage2(message) {
+    let text = stripLabels(message.normalize("NFKC").trim()).toLowerCase();
+    for (const [pattern, replacement] of RULES)
+        text = text.replace(pattern, replacement);
+    return Array.from(text.replace(/\s+/g, " ").trim()).slice(0, MAX_NORMALIZED_CHARS).join("");
+}
+/**
+ * The fingerprint the colony indexes: a hash of the error message alone. The key a trail is filed under is the one
+ * a searcher computes from the line it holds.
+ */
+export function fingerprint2(message) {
+    return PREFIX_2 + createHash("sha256").update(normalizeMessage2(message), "utf8").digest("hex").slice(0, 16);
+}
+/** fp1, the retired fingerprint: the colony no longer indexes it. Use `fingerprint2`. */
 export function fingerprint(runtime, errorType, message) {
     const material = [runtime.trim().toLowerCase(), nfkcLower(errorType).trim(), normalizeMessage(errorType, message)].join(SEPARATOR);
     return PREFIX + createHash("sha256").update(material, "utf8").digest("hex").slice(0, 16);

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/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Colony, MyrmoError, DEFAULT_URL, SDK_VERSION, type ColonyOptions } from "./client.js";
 export { Session, type SessionOptions, type Success, type Hints } from "./session.js";
-export { fingerprint, normalizeMessage, guessErrorType, PREFIX as FINGERPRINT_PREFIX } from "./fingerprint.js";
+export { fingerprint, fingerprint2, normalizeMessage, normalizeMessage2, guessErrorType, PREFIX as FINGERPRINT_PREFIX, PREFIX_2 as FINGERPRINT_PREFIX_2 } from "./fingerprint.js";
 export { redactText, redactValue, type RedactionReport } from "./redact.js";
 export { DEFAULT_MIN_FAILED_ATTEMPTS, SETTINGS, agentIdentity, configPath, minFailedAttempts, publishChoice, readConfig, setSetting, settingsReport, writeConfig, type AgentIdSource, type HookMode, type MyrmoConfig, type SettingRow, type SettingSource } from "./config.js";
 export { detectEnvironment, parsePackage } from "./environment.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Colony, MyrmoError, DEFAULT_URL, SDK_VERSION } from "./client.js";
 export { Session } from "./session.js";
-export { fingerprint, normalizeMessage, guessErrorType, PREFIX as FINGERPRINT_PREFIX } from "./fingerprint.js";
+export { fingerprint, fingerprint2, normalizeMessage, normalizeMessage2, guessErrorType, PREFIX as FINGERPRINT_PREFIX, PREFIX_2 as FINGERPRINT_PREFIX_2 } from "./fingerprint.js";
 export { redactText, redactValue } from "./redact.js";
 export { DEFAULT_MIN_FAILED_ATTEMPTS, SETTINGS, agentIdentity, configPath, minFailedAttempts, publishChoice, readConfig, setSetting, settingsReport, writeConfig } from "./config.js";
 export { detectEnvironment, parsePackage } from "./environment.js";

package/dist/session.js

@@ -3,7 +3,7 @@
 import { minFailedAttempts } from "./config.js";
 import { detectEnvironment, parsePackage } from "./environment.js";
 import { formatResult } from "./format.js";
-import { fingerprint, guessErrorType } from "./fingerprint.js";
+import { fingerprint2, guessErrorType } from "./fingerprint.js";
 import { redactText } from "./redact.js";
 export class Session {
     colony;
@@ -117,6 +117,6 @@ export class Session {
      */
     get lastFingerprint() {
         const last = this.failures.at(-1);
-        return last ? fingerprint(this.options.runtime, last.errorType, redactText(last.message)) : null;
+        return last ? fingerprint2(redactText(last.message)) : null;
     }
 }

package/package.json

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