myrmo 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ npm install myrmo
 ```ts
 import { Colony, formatResult } from "myrmo";
 
-const colony = new Colony(); // MYRMO_URL, MYRMO_PUBLISH, MYRMO_AGENT_ID
+const colony = new Colony(); // MYRMO_URL, MYRMO_PUBLISH (or ~/.myrmo/config.json), MYRMO_AGENT_ID
 
 const result = await colony.search({ error: "Error: error:0308010C:digital envelope routines::unsupported", runtime: "node" });
 for (const hit of result.hits) console.log(hit.strength, hit.trail.solution.root_cause);

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 } 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.2.0";
+export declare const SDK_VERSION = "0.3.0";
 export interface ColonyOptions {
     url?: string;
     apiKey?: string;
@@ -24,6 +24,8 @@ export declare class MyrmoError extends Error {
 export declare class Colony {
     readonly url: string;
     readonly publishMode: PublishMode;
+    /** Where the publish mode came from. `default` means nobody has chosen yet, so nothing is published. */
+    readonly publishSource: "option" | "env" | "file" | "default";
     private readonly apiKey?;
     private readonly agentId?;
     private readonly timeoutMs;

package/dist/client.js

@@ -4,12 +4,13 @@
 //   1. in-process cache (an agent stuck in a loop asks the same thing many times)
 //   2. GET /v1/trails/by-fingerprint/{fp} (cacheable by any CDN; most traffic ends here)
 //   3. POST /v1/search (embedding + vector search; only for errors the colony has not fingerprinted)
+import { publishChoice } from "./config.js";
 import { detectEnvironment, parsePackage } from "./environment.js";
 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.2.0"; // x-release-please-version
+export const SDK_VERSION = "0.3.0"; // x-release-please-version
 export class MyrmoError extends Error {
     status;
     code;
@@ -34,6 +35,8 @@ const env = (key) => (typeof process !== "undefined" ? process.env[key] : undefi
 export class Colony {
     url;
     publishMode;
+    /** Where the publish mode came from. `default` means nobody has chosen yet, so nothing is published. */
+    publishSource;
     apiKey;
     agentId;
     timeoutMs;
@@ -44,8 +47,9 @@ export class Colony {
         this.url = (options.url ?? env("MYRMO_URL") ?? DEFAULT_URL).replace(/\/+$/, "");
         this.apiKey = options.apiKey ?? env("MYRMO_API_KEY");
         this.agentId = options.agentId ?? env("MYRMO_AGENT_ID");
-        const mode = options.publish ?? env("MYRMO_PUBLISH") ?? "off";
-        this.publishMode = ["off", "ask", "auto"].includes(mode) ? mode : "off";
+        const choice = publishChoice(options.publish);
+        this.publishMode = choice.mode;
+        this.publishSource = choice.source;
         this.timeoutMs = options.timeoutMs ?? 10_000;
         this.headers = options.headers ?? {};
         this.cacheTtlMs = options.cacheTtlMs ?? 60_000;

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import type { PublishMode } from "./types.js";
+export interface MyrmoConfig {
+    publish?: PublishMode;
+}
+/** `MYRMO_CONFIG` if set, else `~/.myrmo/config.json`. */
+export declare function configPath(): string;
+export declare function readConfig(): MyrmoConfig;
+export declare function writeConfig(patch: MyrmoConfig): void;
+/**
+ * How publishing is set up, and where that choice came from. `source: "default"` means nobody
+ * has chosen yet: the clients then publish nothing and explain how to choose.
+ */
+export declare function publishChoice(explicit?: PublishMode): {
+    mode: PublishMode;
+    source: "option" | "env" | "file" | "default";
+};

package/dist/config.js

@@ -0,0 +1,47 @@
+// The user's own Myrmo settings, kept in one small file that the TypeScript and Python
+// clients and the MCP server all read:
+//
+//   ~/.myrmo/config.json      { "publish": "auto" }
+//
+// The file records choices only a person should make (whether agents may publish for them),
+// so it is written by `myrmo-mcp config` or by the user's answer to a prompt, never by a model.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const MODES = ["off", "ask", "auto"];
+/** `MYRMO_CONFIG` if set, else `~/.myrmo/config.json`. */
+export function configPath() {
+    return process.env.MYRMO_CONFIG?.trim() || join(homedir(), ".myrmo", "config.json");
+}
+export function readConfig() {
+    try {
+        const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+        const publish = MODES.includes(raw.publish) ? raw.publish : undefined;
+        return publish ? { publish } : {};
+    }
+    catch {
+        // Missing or unreadable: no choice has been made.
+        return {};
+    }
+}
+export function writeConfig(patch) {
+    const path = configPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...readConfig(), ...patch }, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * How publishing is set up, and where that choice came from. `source: "default"` means nobody
+ * has chosen yet: the clients then publish nothing and explain how to choose.
+ */
+export function publishChoice(explicit) {
+    const valid = (v) => MODES.includes(v);
+    if (valid(explicit))
+        return { mode: explicit, source: "option" };
+    const fromEnv = process.env.MYRMO_PUBLISH?.trim();
+    if (valid(fromEnv))
+        return { mode: fromEnv, source: "env" };
+    const fromFile = readConfig().publish;
+    if (fromFile)
+        return { mode: fromFile, source: "file" };
+    return { mode: "off", source: "default" };
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { Colony, MyrmoError, DEFAULT_URL, SDK_VERSION, type ColonyOptions } from
 export { Session, type SessionOptions, type Success, type Hints } from "./session.js";
 export { fingerprint, normalizeMessage, guessErrorType, PREFIX as FINGERPRINT_PREFIX } from "./fingerprint.js";
 export { redactText, redactValue, type RedactionReport } from "./redact.js";
+export { configPath, publishChoice, readConfig, writeConfig, type MyrmoConfig } from "./config.js";
 export { detectEnvironment, parsePackage } from "./environment.js";
 export { formatResult, type FormatOptions } from "./format.js";
 export type * from "./types.js";

package/dist/index.js

@@ -2,6 +2,7 @@ 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 { redactText, redactValue } from "./redact.js";
+export { configPath, publishChoice, readConfig, writeConfig } from "./config.js";
 export { detectEnvironment, parsePackage } from "./environment.js";
 export { formatResult } from "./format.js";
 import { Colony } from "./client.js";

package/dist/redact.js

@@ -116,6 +116,12 @@ const RULES = [
     r("ipv6", String.raw `\b(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}\b|\b(?:[0-9A-Fa-f]{1,4}:){1,5}:(?:[0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4}\b`, "", fixed("ipv6")),
     r("mac", String.raw `\b(?:[0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}\b`, "", fixed("mac")),
     r("hostname", String.raw `(:\/\/|@)(?:[A-Za-z0-9\-]{1,63}\.){1,10}(?:internal|corp|intranet|lan|localdomain|home\.arpa|local)\b`, "i", (m) => m[1] + full("hostname")),
+    // An internal host name on its own, for example in a DNS error. It must end the name: `jdk.internal.misc`
+    // and `com.acme.corp.Service` are Java packages, not hosts. `.local` is left out: it is also a file
+    // suffix (`.env.local`), so it is only redacted inside URLs. The rule is listed twice because a match
+    // consumes the character after it, which would hide a second host separated by a single space.
+    r("hostname", String.raw `(^|[^A-Za-z0-9.\-_])(?:[A-Za-z0-9\-]{1,63}\.){1,10}(?:internal|corp|intranet|lan|localdomain|home\.arpa)($|[^A-Za-z0-9.\-_]|\.\s)`, "i", (m) => m[1] + full("hostname") + m[2]),
+    r("hostname", String.raw `(^|[^A-Za-z0-9.\-_])(?:[A-Za-z0-9\-]{1,63}\.){1,10}(?:internal|corp|intranet|lan|localdomain|home\.arpa)($|[^A-Za-z0-9.\-_]|\.\s)`, "i", (m) => m[1] + full("hostname") + m[2]),
     r("phone", String.raw `\+[0-9]{1,3}[\s.\-]?\(?[0-9]{2,4}\)?[\s.\-]?[0-9]{3,4}[\s.\-]?[0-9]{3,4}\b`, "", fixed("phone")),
     r("card", String.raw `\b[3-6](?:[ \-]?[0-9]){12,18}\b`, "", card),
     r("home_path", String.raw `(\/home\/|\/Users\/)[^/\s'\x22<>]+`, "", (m) => `${m[1]}<user>`),

package/dist/session.d.ts

@@ -9,7 +9,7 @@ export interface SessionOptions {
         model: string;
         framework: string;
     };
-    /** Failed attempts before a fix is worth publishing. Default: MYRMO_MIN_FAILED_ATTEMPTS or 3. */
+    /** Failed attempts before a fix is worth publishing. Default: MYRMO_MIN_FAILED_ATTEMPTS or 1. */
     minFailedAttempts?: number;
 }
 export interface Success {
@@ -33,10 +33,24 @@ export declare class Session {
     private readonly started;
     private readonly failures;
     private matchedExisting;
+    /** Trails the agent followed that did not (fully) work: the fix that follows may be a better alternative. */
+    private readonly triedFailed;
+    private solvedByTrail;
     constructor(colony: Colony, options: SessionOptions);
     get failedAttempts(): number;
     /** Record a failed attempt and search the colony for the error. */
     failed(error: unknown, approach?: string): Promise<Hints>;
+    /**
+     * Report what happened when the agent followed a trail. A trail that failed or only partly
+     * worked is what makes a different fix worth publishing as an alternative, even though the
+     * colony already had an answer for this error. A trail that worked means there is nothing new
+     * to publish.
+     */
+    tried(trailId: string, outcome: "worked" | "partially_worked" | "failed" | "not_applicable", notes?: string): Promise<{
+        trailId: string;
+        counted: boolean;
+        strength: number;
+    }>;
     /**
      * The task succeeded. Returns the drafted trail when it is worth publishing, and publishes
      * it when the colony's publish mode is `auto`. In `ask` mode the caller shows the draft

package/dist/session.js

@@ -10,6 +10,9 @@ export class Session {
     started = Date.now();
     failures = [];
     matchedExisting = false;
+    /** Trails the agent followed that did not (fully) work: the fix that follows may be a better alternative. */
+    triedFailed = [];
+    solvedByTrail = false;
     constructor(colony, options) {
         this.colony = colony;
         this.options = options;
@@ -35,15 +38,31 @@ export class Session {
             this.matchedExisting = true;
         return { result, asPrompt: () => formatResult(result) };
     }
+    /**
+     * Report what happened when the agent followed a trail. A trail that failed or only partly
+     * worked is what makes a different fix worth publishing as an alternative, even though the
+     * colony already had an answer for this error. A trail that worked means there is nothing new
+     * to publish.
+     */
+    async tried(trailId, outcome, notes = "") {
+        const result = await this.colony.report(trailId, outcome, { notes, agentInfo: this.options.agent });
+        if (outcome === "worked")
+            this.solvedByTrail = true;
+        if (outcome === "failed" || outcome === "partially_worked")
+            this.triedFailed.push({ id: trailId, outcome, notes });
+        return result;
+    }
     /**
      * The task succeeded. Returns the drafted trail when it is worth publishing, and publishes
      * it when the colony's publish mode is `auto`. In `ask` mode the caller shows the draft
      * (see `colony.preview`) and calls `colony.publish` after approval.
      */
     async succeeded(success) {
-        const min = this.options.minFailedAttempts ?? Number(process.env.MYRMO_MIN_FAILED_ATTEMPTS ?? 3);
+        const min = this.options.minFailedAttempts ?? Number(process.env.MYRMO_MIN_FAILED_ATTEMPTS ?? 1);
         const last = this.failures.at(-1);
-        if (!last || this.failures.length < min || this.matchedExisting || success.verification.type === "none") {
+        // Nothing new when an existing trail already solved it, or when one matched and was never tried.
+        const covered = this.solvedByTrail || (this.matchedExisting && this.triedFailed.length === 0);
+        if (!last || this.failures.length < min || covered || success.verification.type === "none") {
             return { draft: null };
         }
         const env = detectEnvironment();
@@ -63,7 +82,13 @@ export class Session {
                 summary: (success.summary ?? `${this.options.task}: ${last.message}`).slice(0, 1000).padEnd(20, "."),
                 task_context: this.options.task.slice(0, 1000),
                 raw_logs: last.logs.slice(0, 16_000),
-                failed_approaches: this.failures.slice(0, -1).map((f) => ({ approach: f.approach.slice(0, 500), why_it_failed: f.why.slice(0, 500) })),
+                failed_approaches: [
+                    ...this.failures.slice(0, -1).map((f) => ({ approach: f.approach.slice(0, 500), why_it_failed: f.why.slice(0, 500) })),
+                    ...this.triedFailed.map((t) => ({
+                        approach: `Followed Myrmo trail ${t.id}`,
+                        why_it_failed: (t.notes || (t.outcome === "failed" ? "it did not work in this environment" : "it only partly worked")).slice(0, 500),
+                    })),
+                ],
             },
             solution: {
                 root_cause: success.rootCause,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "myrmo",
-  "version": "0.2.0",
-  "description": "Myrmo client: shared memory of solved errors for AI agents. Fingerprints, redaction and the colony API.",
+  "version": "0.3.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",
   "bugs": {
@@ -34,10 +34,19 @@
   },
   "keywords": [
     "ai-agents",
+    "agent-memory",
+    "error-resolution",
+    "debugging",
+    "troubleshooting",
+    "stack-overflow-for-agents",
     "llm",
     "mcp",
-    "errors",
-    "memory"
+    "model-context-protocol",
+    "a2a",
+    "claude-code",
+    "cursor",
+    "langchain",
+    "crewai"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",