myrmo 0.3.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 (or ~/.myrmo/config.json), 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.3.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. */
@@ -28,6 +33,7 @@ export declare class Colony {
     readonly publishSource: "option" | "env" | "file" | "default";
     private readonly apiKey?;
     private readonly agentId?;
+    private readonly model?;
     private readonly timeoutMs;
     private readonly headers;
     private readonly cacheTtlMs;
@@ -37,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,13 +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 { 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.3.0"; // x-release-please-version
+export const SDK_VERSION = "0.4.0"; // x-release-please-version
 export class MyrmoError extends Error {
     status;
     code;
@@ -39,6 +39,7 @@ export class Colony {
     publishSource;
     apiKey;
     agentId;
+    model;
     timeoutMs;
     headers;
     cacheTtlMs;
@@ -46,7 +47,9 @@ 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");
+        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;
@@ -54,14 +57,18 @@ export class Colony {
         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,
@@ -93,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;
@@ -107,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 = {
@@ -127,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

@@ -1,6 +1,7 @@
 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;
@@ -14,3 +15,13 @@ 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

@@ -1,13 +1,18 @@
 // 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" }
+//   ~/.myrmo/config.json      { "publish": "auto", "agent_id": "3f9c0a7e2b1d4c68a5e0b7d91c2f4a86" }
 //
-// 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.
+// `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() {
@@ -16,8 +21,12 @@ export function configPath() {
 export function readConfig() {
     try {
         const raw = JSON.parse(readFileSync(configPath(), "utf8"));
-        const publish = MODES.includes(raw.publish) ? raw.publish : undefined;
-        return publish ? { publish } : {};
+        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.
@@ -45,3 +54,30 @@ export function publishChoice(explicit) {
         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,7 +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 { 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,7 +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 { 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/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,6 +1,6 @@
 {
   "name": "myrmo",
-  "version": "0.3.0",
+  "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",