myrmo 0.4.0 → 0.6.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.4.0";
+export declare const SDK_VERSION = "0.6.0";
 export interface ColonyOptions {
     url?: string;
     apiKey?: string;
@@ -61,6 +61,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,7 @@ 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.4.0"; // x-release-please-version
+export const SDK_VERSION = "0.6.0"; // x-release-please-version
 export class MyrmoError extends Error {
     status;
     code;
@@ -161,6 +161,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);
+            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);

package/dist/config.d.ts

@@ -1,20 +1,82 @@
 import type { PublishMode } from "./types.js";
+export type HookMode = "on" | "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. */
+    hook?: HookMode;
+    /** Send no agent id at all. */
+    anonymous?: boolean;
 }
+export declare const DEFAULT_MIN_FAILED_ATTEMPTS = 1;
 /** `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;
+/** Merge `patch` into the file. A key set to `undefined` is removed, which restores its default. */
+export declare function writeConfig(patch: {
+    [K in keyof MyrmoConfig]?: MyrmoConfig[K] | undefined;
+}): 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.
+ * has chosen yet: the clients then publish nothing until the user has been asked once (the MCP
+ * server asks the first time an agent wants to publish, with "ask" preselected).
  */
 export declare function publishChoice(explicit?: PublishMode): {
     mode: PublishMode;
     source: "option" | "env" | "file" | "default";
 };
+export type SettingSource = "option" | "env" | "file" | "default";
+/** Failed attempts before a fix is worth publishing: option, then MYRMO_MIN_FAILED_ATTEMPTS, then the file, then 1. */
+export declare function minFailedAttempts(explicit?: number): {
+    value: number;
+    source: SettingSource;
+};
+/** What `myrmo-mcp config` can change: its name, what it does, the values it takes, and the default. */
+export declare const SETTINGS: readonly [{
+    readonly key: "publish";
+    readonly file: "publish";
+    readonly values: "ask | auto | off";
+    readonly default: "ask (asked the first time an agent wants to publish)";
+    readonly about: "Whether agents may publish fixes for you. ask shows you each one first.";
+}, {
+    readonly key: "min-failed-attempts";
+    readonly file: "min_failed_attempts";
+    readonly values: "0 to 20";
+    readonly default: string;
+    readonly about: "Failed attempts before a fix is worth publishing. Higher means fewer, more selective trails.";
+}, {
+    readonly key: "hook";
+    readonly file: "hook";
+    readonly values: "on | off";
+    readonly default: "on";
+    readonly about: "Claude Code plugin: remind the agent to search when a command fails.";
+}, {
+    readonly key: "anonymous";
+    readonly file: "anonymous";
+    readonly values: "true | false";
+    readonly default: "false";
+    readonly about: "Send no agent id at all (reports then count by address).";
+}];
+export interface SettingRow {
+    key: string;
+    value: string;
+    source: SettingSource;
+    about: string;
+    values: string;
+    default: string;
+}
+/** Every setting with its current value and where that value comes from. */
+export declare function settingsReport(): SettingRow[];
+/** Change one setting from its CLI name. The value `reset` removes it from the file (back to the default). */
+export declare function setSetting(key: string, value: string): {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+};
 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

package/dist/config.js

@@ -1,17 +1,22 @@
 // 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" }
+//   ~/.myrmo/config.json      { "publish": "ask", "min_failed_attempts": 1, "hook": "on", "agent_id": "3f9c..." }
 //
-// `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.
+// Everything works with no file at all: every setting has a default. The file only records what a
+// person chose. `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.
+//
+// For each setting the order is: an explicit option, the environment variable, this file, the default.
 import { randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+export const DEFAULT_MIN_FAILED_ATTEMPTS = 1;
+const MAX_MIN_FAILED_ATTEMPTS = 20;
 const AGENT_ID = /^[A-Za-z0-9_-]{8,64}$/;
 const MODES = ["off", "ask", "auto"];
 /** `MYRMO_CONFIG` if set, else `~/.myrmo/config.json`. */
@@ -26,6 +31,13 @@ export function readConfig() {
             config.publish = raw.publish;
         if (typeof raw.agent_id === "string" && AGENT_ID.test(raw.agent_id))
             config.agent_id = raw.agent_id;
+        const attempts = parseAttempts(raw.min_failed_attempts);
+        if (attempts !== undefined)
+            config.min_failed_attempts = attempts;
+        if (raw.hook === "on" || raw.hook === "off")
+            config.hook = raw.hook;
+        if (typeof raw.anonymous === "boolean")
+            config.anonymous = raw.anonymous;
         return config;
     }
     catch {
@@ -33,6 +45,11 @@ export function readConfig() {
         return {};
     }
 }
+function parseAttempts(value) {
+    const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+    return typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= MAX_MIN_FAILED_ATTEMPTS ? n : undefined;
+}
+/** Merge `patch` into the file. A key set to `undefined` is removed, which restores its default. */
 export function writeConfig(patch) {
     const path = configPath();
     mkdirSync(dirname(path), { recursive: true });
@@ -40,7 +57,8 @@ export function writeConfig(patch) {
 }
 /**
  * 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.
+ * has chosen yet: the clients then publish nothing until the user has been asked once (the MCP
+ * server asks the first time an agent wants to publish, with "ask" preselected).
  */
 export function publishChoice(explicit) {
     const valid = (v) => MODES.includes(v);
@@ -54,6 +72,75 @@ export function publishChoice(explicit) {
         return { mode: fromFile, source: "file" };
     return { mode: "off", source: "default" };
 }
+/** Failed attempts before a fix is worth publishing: option, then MYRMO_MIN_FAILED_ATTEMPTS, then the file, then 1. */
+export function minFailedAttempts(explicit) {
+    const fromOption = parseAttempts(explicit);
+    if (fromOption !== undefined)
+        return { value: fromOption, source: "option" };
+    const fromEnv = parseAttempts(process.env.MYRMO_MIN_FAILED_ATTEMPTS);
+    if (fromEnv !== undefined)
+        return { value: fromEnv, source: "env" };
+    const fromFile = readConfig().min_failed_attempts;
+    if (fromFile !== undefined)
+        return { value: fromFile, source: "file" };
+    return { value: DEFAULT_MIN_FAILED_ATTEMPTS, source: "default" };
+}
+/** What `myrmo-mcp config` can change: its name, what it does, the values it takes, and the default. */
+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: "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. */
+export function settingsReport() {
+    const file = readConfig();
+    const publish = publishChoice();
+    const attempts = minFailedAttempts();
+    const hookEnv = process.env.MYRMO_HOOK?.trim().toLowerCase();
+    const anonEnv = process.env.MYRMO_ANONYMOUS?.trim().toLowerCase();
+    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" },
+        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 }));
+}
+/** Change one setting from its CLI name. The value `reset` removes it from the file (back to the default). */
+export function setSetting(key, value) {
+    const def = SETTINGS.find((s) => s.key === key);
+    if (!def)
+        return { ok: false, error: `Unknown setting "${key}". Settings: ${SETTINGS.map((s) => s.key).join(", ")}.` };
+    if (value === "reset") {
+        writeConfig({ [def.file]: undefined });
+        return { ok: true, message: `${key} is back to its default (${def.default}).` };
+    }
+    let patch;
+    if (key === "publish") {
+        if (!MODES.includes(value))
+            return { ok: false, error: "publish takes ask, auto or off." };
+        patch = { publish: value };
+    }
+    else if (key === "min-failed-attempts") {
+        const n = parseAttempts(value);
+        if (n === undefined)
+            return { ok: false, error: `min-failed-attempts takes a whole number from 0 to ${MAX_MIN_FAILED_ATTEMPTS}.` };
+        patch = { min_failed_attempts: n };
+    }
+    else if (key === "hook") {
+        if (value !== "on" && value !== "off")
+            return { ok: false, error: "hook takes on or off." };
+        patch = { hook: value };
+    }
+    else {
+        if (!["true", "false"].includes(value))
+            return { ok: false, error: "anonymous takes true or false." };
+        patch = { anonymous: value === "true" };
+    }
+    writeConfig(patch);
+    return { ok: true, message: `Saved to ${configPath()}: ${key} = ${value}.` };
+}
 /**
  * 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
@@ -69,6 +156,8 @@ export function agentIdentity(explicit) {
         return { id: fromEnv, source: "env" };
     if (["1", "true"].includes(process.env.MYRMO_ANONYMOUS?.trim().toLowerCase() ?? ""))
         return { source: "none" };
+    if (readConfig().anonymous === true)
+        return { source: "none" };
     const stored = readConfig().agent_id;
     if (stored)
         return { id: stored, source: "file" };

package/dist/format.d.ts

@@ -3,5 +3,9 @@ export interface FormatOptions {
     /** Include commands flagged high risk. Off by default. */
     includeHighRisk?: boolean;
     maxTrails?: number;
+    /** Failed attempts before a fix is worth publishing, for the hint after a search with no match. Default: the configured minimum. */
+    minFailedAttempts?: number;
 }
+/** "at least one failed attempt", "3 or more failed attempts". */
+export declare function attemptsPhrase(n: number): string;
 export declare function formatResult(result: SearchResult, opts?: FormatOptions): string;

package/dist/format.js

@@ -1,5 +1,10 @@
 // Render search results for a language model: compact, explicit about provenance, and
 // wrapped as untrusted data. Used by the MCP server and by Session hints.
+import { minFailedAttempts } from "./config.js";
+/** "at least one failed attempt", "3 or more failed attempts". */
+export function attemptsPhrase(n) {
+    return n <= 1 ? "at least one failed attempt" : `${n} or more failed attempts`;
+}
 // Trail text is written by strangers and is pasted into a model's context, so every field is
 // rendered so that it cannot forge structure: no line breaks inside a single-line field, no
 // look-alike of our own envelope tags, and code fences longer than anything they contain.
@@ -45,7 +50,7 @@ function formatHit(hit, index, total, opts) {
     const o = hit.outcomes;
     const lines = [];
     const overlap = hit.match.environment_overlap === null ? "" : ` · environment overlap ${hit.match.environment_overlap}`;
-    lines.push(`## Trail ${index + 1} of ${total} · id ${safeId(hit.trailId)}`, `strength ${hit.strength} · worked ${o.worked} · partially ${o.partially_worked} · failed ${o.failed} · matched by ${clip(String(hit.match.via), 16)} (${hit.match.score})${overlap} · risk ${clip(String(hit.risk.level), 16)}`, `Environment: ${[t.environment.os, t.environment.os_version, t.environment.arch, `${t.environment.runtime.name} ${t.environment.runtime.version}`].map((x) => clip(x, 64)).filter(Boolean).join(" · ")}`, `Error: ${errorLine(t.problem.error_type, t.problem.error_message)}`, `Root cause: ${clip(t.solution.root_cause, 800)}`);
+    lines.push(`## Trail ${index + 1} of ${total} · id ${safeId(hit.trailId)}`, `strength ${hit.strength} · worked ${o.worked} · partially ${o.partially_worked} · failed ${o.failed} · matched by ${clip(String(hit.match.via), 16)} (${hit.match.score})${overlap} · risk ${clip(String(hit.risk.level), 16)}`, `Environment: ${[t.environment.os, t.environment.os_version, t.environment.arch, t.environment.container && t.environment.container !== "none" ? `in ${t.environment.container}` : "", `${t.environment.runtime.name} ${t.environment.runtime.version}`].map((x) => clip(x, 64)).filter(Boolean).join(" · ")}`, `Error: ${errorLine(t.problem.error_type, t.problem.error_message)}`, `Root cause: ${clip(t.solution.root_cause, 800)}`);
     const dead = t.problem.failed_approaches ?? [];
     if (dead.length) {
         lines.push("Dead ends, do not retry:");
@@ -84,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 3 or more failed attempts and you verify the fix, publish it with myrmo_publish so the next agent does not have to.",
+            `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.`,
         ].join("\n");
     }
     return [

package/dist/index.d.ts

@@ -2,9 +2,9 @@ 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 { 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";
-export { formatResult, type FormatOptions } from "./format.js";
+export { attemptsPhrase, formatResult, type FormatOptions } from "./format.js";
 export type * from "./types.js";
 import { Session, type SessionOptions } from "./session.js";
 declare module "./client.js" {

package/dist/index.js

@@ -2,9 +2,9 @@ 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 { DEFAULT_MIN_FAILED_ATTEMPTS, SETTINGS, agentIdentity, configPath, minFailedAttempts, publishChoice, readConfig, setSetting, settingsReport, writeConfig } from "./config.js";
 export { detectEnvironment, parsePackage } from "./environment.js";
-export { formatResult } from "./format.js";
+export { attemptsPhrase, formatResult } from "./format.js";
 import { Colony } from "./client.js";
 import { Session } from "./session.js";
 Colony.prototype.session = function (options) {

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 1. */
+    /** Failed attempts before a fix is worth publishing. Default: MYRMO_MIN_FAILED_ATTEMPTS, the settings file, or 1. */
     minFailedAttempts?: number;
 }
 export interface Success {

package/dist/session.js

@@ -1,5 +1,6 @@
 // A session wraps one task: it searches the colony on every new error, records failed
 // approaches, and drafts a trail when the task finally succeeds after enough failures.
+import { minFailedAttempts } from "./config.js";
 import { detectEnvironment, parsePackage } from "./environment.js";
 import { formatResult } from "./format.js";
 import { fingerprint, guessErrorType } from "./fingerprint.js";
@@ -58,7 +59,7 @@ export class Session {
      * (see `colony.preview`) and calls `colony.publish` after approval.
      */
     async succeeded(success) {
-        const min = this.options.minFailedAttempts ?? Number(process.env.MYRMO_MIN_FAILED_ATTEMPTS ?? 1);
+        const min = minFailedAttempts(this.options.minFailedAttempts).value;
         const last = this.failures.at(-1);
         // 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);

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.4.0",
+  "version": "0.6.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",