myrmo 0.2.0 → 0.4.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); the agent id is created for you
 
 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,12 +2,17 @@ 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.4.0";
 export interface ColonyOptions {
     url?: string;
     apiKey?: string;
-    /** Pseudonymous id, 8–64 chars of [A-Za-z0-9_-]. */
-    agentId?: string;
+    /**
+     * Pseudonymous id, 8–64 chars of [A-Za-z0-9_-]. By default one is created on first use and kept in
+     * `~/.myrmo/config.json`; `false` sends none (a server that forwards its callers' own header).
+     */
+    agentId?: string | false;
+    /** The model this client runs for; sent as X-Myrmo-Model for aggregate counters. Default: MYRMO_AGENT_MODEL. */
+    model?: string;
     publish?: PublishMode;
     timeoutMs?: number;
     /** Extra headers on every request, e.g. X-Forwarded-For from a trusted proxy. */
@@ -24,8 +29,11 @@ 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 model?;
     private readonly timeoutMs;
     private readonly headers;
     private readonly cacheTtlMs;
@@ -35,7 +43,7 @@ export declare class Colony {
     private cached;
     private remember;
     /** Trails for a fingerprint, or `null` when the colony has none. */
-    lookup(fp: string): Promise<SearchResult | null>;
+    lookup(fp: string, model?: string): Promise<SearchResult | null>;
     /** Find trails for an error: fingerprint first, semantic search when there is no exact match. */
     search(query: SearchQuery): Promise<SearchResult>;
     /** Tell the colony whether a trail worked. Failures matter as much as successes. */

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 { agentIdentity, 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.4.0"; // x-release-please-version
 export class MyrmoError extends Error {
     status;
     code;
@@ -34,8 +35,11 @@ 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;
+    model;
     timeoutMs;
     headers;
     cacheTtlMs;
@@ -43,21 +47,28 @@ export class Colony {
     constructor(options = {}) {
         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";
+        this.agentId = agentIdentity(options.agentId).id;
+        const model = (options.model ?? env("MYRMO_AGENT_MODEL"))?.trim();
+        this.model = model && model.toLowerCase() !== "unknown" ? model : undefined;
+        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;
     }
-    async request(method, path, body) {
+    async request(method, path, body, extra) {
         const headers = { accept: "application/json", "user-agent": `myrmo-js/${SDK_VERSION}`, ...this.headers };
         if (body !== undefined)
             headers["content-type"] = "application/json";
         if (this.apiKey)
             headers.authorization = `Bearer ${this.apiKey}`;
-        if (this.agentId)
+        // A header the caller passed (a hosted server forwarding its users' ids) wins over this client's own.
+        if (this.agentId && !Object.keys(headers).some((k) => k.toLowerCase() === "x-myrmo-agent"))
             headers["x-myrmo-agent"] = this.agentId;
+        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,
@@ -89,11 +100,11 @@ export class Colony {
         this.cache.set(key, { at: Date.now(), value });
     }
     /** Trails for a fingerprint, or `null` when the colony has none. */
-    async lookup(fp) {
+    async lookup(fp, model) {
         const hit = this.cached(fp);
         if (hit !== undefined)
             return hit;
-        const { status, data } = await this.request("GET", `/v1/trails/by-fingerprint/${encodeURIComponent(fp)}`);
+        const { status, data } = await this.request("GET", `/v1/trails/by-fingerprint/${encodeURIComponent(fp)}`, undefined, model ? { "x-myrmo-model": model } : undefined);
         const value = status === 404 ? null : { fingerprint: data.fingerprint, hits: data.results.map(toHit), notice: data.notice, source: "fingerprint" };
         this.remember(fp, value);
         return value;
@@ -103,7 +114,7 @@ export class Colony {
         const error = redactText(query.error);
         const errorType = query.errorType ?? guessErrorType(error);
         const fp = fingerprint(query.runtime ?? "", errorType, error);
-        const exact = await this.lookup(fp);
+        const exact = await this.lookup(fp, query.model);
         if (exact && exact.hits.length > 0)
             return exact;
         const environment = {
@@ -123,7 +134,7 @@ export class Colony {
             environment,
             limit: query.limit ?? 3,
             min_strength: query.minStrength ?? 0,
-        });
+        }, query.model ? { "x-myrmo-model": query.model } : undefined);
         const value = { fingerprint: data.fingerprint, hits: data.results.map(toHit), notice: data.notice, source: "search" };
         this.remember(key, value);
         return value;

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+import type { PublishMode } from "./types.js";
+export interface MyrmoConfig {
+    publish?: PublishMode;
+    agent_id?: string;
+}
+/** `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";
+};
+export type AgentIdSource = "option" | "env" | "file" | "generated" | "none";
+/**
+ * Who this client says it is. Nothing to configure: the first run creates a random id and keeps it in
+ * the config file. `MYRMO_AGENT_ID` (or the `agentId` option) overrides it, `false` or
+ * `MYRMO_ANONYMOUS=1` sends none. If the file cannot be written the id lives for this process only.
+ */
+export declare function agentIdentity(explicit?: string | false): {
+    id?: string;
+    source: AgentIdSource;
+};

package/dist/config.js

@@ -0,0 +1,83 @@
+// 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", "agent_id": "3f9c0a7e2b1d4c68a5e0b7d91c2f4a86" }
+//
+// `publish` is a choice 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.
+// `agent_id` is a random pseudonym the client creates by itself the first time it runs, so that
+// reports from different machines behind one address are not mistaken for a single agent. It holds
+// no personal data and can be deleted at any time.
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const AGENT_ID = /^[A-Za-z0-9_-]{8,64}$/;
+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 config = {};
+        if (MODES.includes(raw.publish))
+            config.publish = raw.publish;
+        if (typeof raw.agent_id === "string" && AGENT_ID.test(raw.agent_id))
+            config.agent_id = raw.agent_id;
+        return config;
+    }
+    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" };
+}
+/**
+ * Who this client says it is. Nothing to configure: the first run creates a random id and keeps it in
+ * the config file. `MYRMO_AGENT_ID` (or the `agentId` option) overrides it, `false` or
+ * `MYRMO_ANONYMOUS=1` sends none. If the file cannot be written the id lives for this process only.
+ */
+export function agentIdentity(explicit) {
+    if (explicit === false)
+        return { source: "none" };
+    if (explicit)
+        return { id: explicit, source: "option" };
+    const fromEnv = process.env.MYRMO_AGENT_ID?.trim();
+    if (fromEnv)
+        return { id: fromEnv, source: "env" };
+    if (["1", "true"].includes(process.env.MYRMO_ANONYMOUS?.trim().toLowerCase() ?? ""))
+        return { source: "none" };
+    const stored = readConfig().agent_id;
+    if (stored)
+        return { id: stored, source: "file" };
+    const id = randomUUID().replace(/-/g, "");
+    try {
+        writeConfig({ agent_id: id });
+    }
+    catch {
+        // A read-only home directory: the id then lasts as long as this process.
+    }
+    return { id, source: "generated" };
+}

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 { agentIdentity, configPath, publishChoice, readConfig, writeConfig, type AgentIdSource, 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 { agentIdentity, 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/dist/types.d.ts

@@ -124,6 +124,8 @@ export interface SearchQuery {
     packages?: (string | Package)[];
     limit?: number;
     minStrength?: number;
+    /** The model asking, for aggregate counters. Overrides the client's own `model` for this search. */
+    model?: string;
 }
 /** A trail held by the colony until a person approves it in a browser. */
 export interface DraftResult {

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.4.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",