@cotal-ai/connector-core 0.35.0 → 0.37.0

package/dist/agent.js

@@ -1,12 +1,11 @@
 import { execFile } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { hostname } from "node:os";
-import { normalizeMentions, subjectMatches, isConcreteChannel, assertValidChannel, channelInAllow, resolvePeer as resolvePeerInRoster, CotalEndpoint, BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, partsToText, } from "@cotal-ai/core";
-/** Client-side request window for the manager's readiness-waiting `start` op (#159 B1): the manager
- *  replies only on a REAL outcome — presence join, process exit, or its ~30s readiness backstop —
- *  so a spawn request must OUTLIVE that window, not the 5s op default. The tier rule forbids
- *  importing the manager's READINESS_TIMEOUT_MS here; the launch-parity smoke enforces the
- *  relation by test. */
+import { normalizeMentions, subjectMatches, isConcreteChannel, assertValidChannel, channelInAllow, resolvePeer as resolvePeerInRoster, CotalEndpoint, BASELINE_LIFECYCLE_ENDPOINT, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, renderLifecycleBlocked, partsToText, } from "@cotal-ai/core";
+/** Client-side floor for a spawn action's submit + follow. The manager acceptance carries the exact
+ *  connector-selected readiness budget, and core extends the follow through that budget plus
+ *  delivery margin. This floor still outlives the manager's generic 30s default and protects
+ *  older responders whose acceptance predates that field. */
 export const SPAWN_TIMEOUT_MS = 40_000;
 /** Grace for a mesh op issued while the link is still coming up. `start()` deliberately returns
  *  immediately so the connector's MCP surface boots while the broker is absent — which means a
@@ -96,22 +95,6 @@ function sleep(ms) {
 function ingestDedupKey(id) {
     return id === "" ? undefined : id;
 }
-/**
- * A thin, mesh-native agent: a {@link CotalEndpoint} plus a buffered inbox and
- * name-based peer resolution. This is the shared core behind the MCP server
- * (and, later, the lifecycle hooks) — it owns the NATS connection and presence.
- *
- * Connecting is resilient: {@link start} kicks off a background retry loop so the
- * MCP server is responsive immediately even if the mesh isn't up yet.
- *
- * Emits `"incoming"` (InboxItem) when a message is buffered or an unacked durable copy
- * redelivers, so a push layer can apply its normal delivery policy again; `"mention-wake"`
- * (InboxItem) when a `focus`-mode agent is @-mentioned on a channel — the body was
- * acked-and-dropped (not buffered), so this
- * only asks the push layer to *wake* the agent to pull it; `"wake"` (no payload) to ask that
- * layer to wake the session now (the Stop→idle flush of held messages); `"error"` (Error) for
- * endpoint faults.
- */
 export class MeshAgent extends EventEmitter {
     ep;
     config;
@@ -143,10 +126,16 @@ export class MeshAgent extends EventEmitter {
     protectedDropIds = new Set();
     dropUnsafe = false;
     _connected = false;
+    /** Raw NATS transport liveness, separate from `_connected` (the full Cotal bind/readiness). */
+    _transportConnected = false;
+    /** Wall-clock time of the latest inbox drain that actually committed at least one delivery.
+     *  This is measured only after the backing acknowledgements succeed, never inferred from a read
+     *  attempt or from an empty inbox. */
+    _lastInboxDrainedAt;
     /** Latest connection failure, retained until the endpoint binds so a bounded readiness gate can
      * explain why an otherwise healthy host never joined the mesh. */
     lastConnectionError;
-    endpointErrorLog = new Map();
+    endpointNoticeLog = new Map();
     _status = "idle";
     _attention = "open"; // F3: fail-open default; reset to open on SessionStart
     _recallCursor = { ts: 0, id: "" };
@@ -174,7 +163,7 @@ export class MeshAgent extends EventEmitter {
     recvKeySeq = 0;
     focusExcludedIds = new Map();
     focusRecallUnsafeChannels = new Set();
-    stopping = false;
+    _stopping = false;
     constructor(config) {
         super();
         this.config = config;
@@ -218,14 +207,34 @@ export class MeshAgent extends EventEmitter {
         });
         this.ep.on("message", (m, d, meta) => this.ingest(m, d, meta));
         this.ep.on("error", (e) => this.handleEndpointError(e));
+        // A warning is a condition the endpoint is already surviving. Log it through the same bounded
+        // operator sink, but never turn it into connectionIssue: readiness is still true.
+        this.ep.on("warning", (e) => this.handleEndpointWarning(e));
+        // Two guards, and the comments sit out here so neither anchors a mutation on prose. An
+        // in-flight initial bind or rebuild can finish after stop() cleared local state, and shutdown is
+        // terminal for this MeshAgent, so a late endpoint edge must not resurrect transport. Separately,
+        // nats.js and clean shutdown can both confirm the same edge; a duplicate carries no state change
+        // and must not wake consumers or let an old confirmation look like a new outage.
+        this.ep.on("transport", (e) => {
+            if (this._stopping)
+                return;
+            if (this._transportConnected === e.connected)
+                return;
+            this._transportConnected = e.connected;
+            this.emit("transport", e);
+        });
         // The endpoint's (re)binds are the single source of truth for connectedness: this fires on
         // initial start, manual reconnect, AND the background self-heal — so a recovery the endpoint
         // did on its own can't leave us thinking we're offline (which would skip stop() → leak).
+        // Same stop race as the transport handler above: a late connectAndBind completion is not a new
+        // session. Kept out of the block so the guard can be anchored on code alone.
         this.ep.on("connection", (e) => {
+            if (this._stopping)
+                return;
             this._connected = e.connected;
             if (e.connected) {
                 this.lastConnectionError = undefined;
-                this.endpointErrorLog.clear();
+                this.endpointNoticeLog.clear();
             }
             this.emit("connection", e);
         });
@@ -236,10 +245,34 @@ export class MeshAgent extends EventEmitter {
     get connected() {
         return this._connected;
     }
-    /** The latest safe diagnostic for a connection that has not become live yet. */
+    /** Whether this session's current NATS transport is live, independent of full endpoint readiness. */
+    get transportConnected() {
+        return this._transportConnected;
+    }
+    /** Latest pre-bind failure. A successful bind clears it; stop preserves it for post-mortem diagnosis. */
     get connectionIssue() {
         return this.lastConnectionError;
     }
+    /** The latest successful, non-empty inbox drain in this session. */
+    get lastInboxDrainedAt() {
+        return this._lastInboxDrainedAt;
+    }
+    /** Whether {@link stop} has been called. Terminal, and never cleared: a stopped session does not
+     *  serve again. This is the ONLY way to tell a deliberate shutdown from a lost connection, because
+     *  `stop()` clears readiness and transport together, so those two read identically in both cases. */
+    get stopping() {
+        return this._stopping;
+    }
+    /** The three liveness facts combined, in one place. Every combination maps, so a caller never has
+     *  to guess what an unlisted pair means, and a caller that disagrees with this reading can still
+     *  read {@link connected}, {@link transportConnected} and {@link stopping} directly. */
+    get connectionState() {
+        if (this._stopping)
+            return "stopped";
+        if (this._connected)
+            return this._transportConnected ? "ready" : "degraded";
+        return this._transportConnected ? "connecting" : "disconnected";
+    }
     /** Wait for the endpoint's real post-bind connection signal. `start()` deliberately stays
      * background for connectors whose MCP surface must boot while the broker is absent; a host that
      * advertises mesh readiness uses this bounded gate before making that claim. */
@@ -285,7 +318,7 @@ export class MeshAgent extends EventEmitter {
         return this.connectLoop(retryMs);
     }
     async connectLoop(retryMs) {
-        while (!this.stopping && !this._connected) {
+        while (!this._stopping && !this._connected) {
             try {
                 await this.ep.start();
                 // _connected is set by the endpoint's "connection" event (fired inside start()), not here.
@@ -293,6 +326,11 @@ export class MeshAgent extends EventEmitter {
             }
             catch (e) {
                 const error = e instanceof Error ? e : new Error(String(e));
+                // stop() can win while the initial endpoint start is still pending. A rejection arriving
+                // after that terminal decision is teardown noise, not a new connectionIssue for the stopped
+                // session, and there is no next retry to explain or sleep toward.
+                if (this._stopping)
+                    return;
                 this.lastConnectionError = error.message;
                 this.log(`mesh unreachable (${error.message}); retrying in ${retryMs}ms`);
                 await sleep(retryMs);
@@ -300,7 +338,14 @@ export class MeshAgent extends EventEmitter {
         }
     }
     async stop() {
-        this.stopping = true;
+        this._stopping = true;
+        // stop() is a local terminal fact. Do not wait for an endpoint event that intentionally ignores
+        // its own stopped close, or leave a cleanly stopped session reporting either state as live.
+        this._connected = false;
+        if (this._transportConnected) {
+            this._transportConnected = false;
+            this.emit("transport", { connected: false });
+        }
         // Unconditional: a background self-heal can flip _connected without us, so a `_connected`
         // guard could skip the stop and leak the live connection/heartbeat/supervisor. ep.stop() is
         // idempotent (early-returns once stopped), so calling it when already-down is a noop.
@@ -312,7 +357,7 @@ export class MeshAgent extends EventEmitter {
      *  interruptible. Returns a one-line status for the caller to surface (e.g. the
      *  cotal_reconnect tool → TUI); on failure the endpoint keeps retrying in the background. */
     async reconnect() {
-        if (this.stopping) {
+        if (this._stopping) {
             return {
                 ok: false,
                 message: "This session is shutting down, so its Cotal mesh connection cannot be reconnected. Start a new session instead.",
@@ -379,8 +424,10 @@ export class MeshAgent extends EventEmitter {
         //  - `quiet` → buffer ambient as pull-only; an @mention remains automatic. Overrides global
         //    `focus` so "retain this channel, but only surface ambient on explicit pull" stays expressible.
         // Focus (global, only when NOT overridden): channel ambient AND @mentions are acked-and-dropped —
-        // they stay recallable via cotal_inbox (recallAmbient); an @mention still *wakes* (mention-wake),
-        // body pulled (F4=B), never auto-injected (the mention tag is payload-forgeable).
+        // they stay recallable via cotal_inbox (recallAmbient), or if recall itself cannot vouch for the
+        // channel (replay=off, or a wildcard join — #977), that is reported rather than left silent; an
+        // @mention still *wakes* (mention-wake), body pulled (F4=B), never auto-injected (the mention
+        // tag is payload-forgeable).
         if (item.kind === "channel") {
             const cm = this.channelModes.get(item.channel ?? "");
             // chatFrontier() is asynchronous. Channel traffic retained while entering focus must not also
@@ -428,7 +475,7 @@ export class MeshAgent extends EventEmitter {
         this.buffer(item, delivery.ack, false);
     }
     buffer(item, ack, pullOnly) {
-        this.inbox.push({ item, ack, pullOnly });
+        this.inbox.push({ item, ack, pullOnly, receivedAt: Date.now() });
         if (this.inbox.length > MAX_INBOX) {
             // Prefer sacrificing pull-only backlog so it cannot crowd out DMs/mentions. Overflow remains
             // bounded local loss: evicted items are acked without being marked handled.
@@ -642,7 +689,10 @@ export class MeshAgent extends EventEmitter {
         // acking only the selected — silent loss by selection. Identity removes exactly what was taken.
         const taken = new Set(selected);
         this.inbox = this.inbox.filter((p) => !taken.has(p));
-        return this.commitPending(selected);
+        const items = this.commitPending(selected);
+        if (items.length)
+            this._lastInboxDrainedAt = Date.now();
+        return items;
     }
     /** Ack exact surfaced deliveries without assuming they still form the physical inbox prefix.
      *  Takes RECEIVE keys ({@link InboxItem.recvKey}): the wire id for real messages, a minted key
@@ -664,6 +714,8 @@ export class MeshAgent extends EventEmitter {
         }
         this.inbox = this.inbox.filter((p) => !present.has(p.item.recvKey));
         const items = this.commitPending(selected);
+        if (items.length)
+            this._lastInboxDrainedAt = Date.now();
         for (const id of requested) {
             // A MINTED key (an id-less delivery) is never handled-authority: its wire id is "", which
             // markHandled already refuses, so skipping it here is the same at-least-once stance rather
@@ -708,6 +760,17 @@ export class MeshAgent extends EventEmitter {
     inboxCount(scope = "all") {
         return scope === "all" ? this.inbox.length : this.inbox.filter((p) => this.inScope(p, scope)).length;
     }
+    /** Local receive time of the oldest still-buffered automatic delivery, if any. */
+    oldestAutomaticReceivedAt() {
+        let oldest;
+        for (const pending of this.inbox) {
+            if (pending.pullOnly)
+                continue;
+            if (oldest === undefined || pending.receivedAt < oldest)
+                oldest = pending.receivedAt;
+        }
+        return oldest;
+    }
     /**
      * How far this session has read the focus-mode channel recall.
      *
@@ -913,19 +976,24 @@ export class MeshAgent extends EventEmitter {
     }
     /** Focus recall: the channel ambient + @mentions ack-dropped since this agent entered focus,
      *  read back from the chat stream on demand and **replay-gated per channel** (a `replay=off`
-     *  channel yields nothing — recall must not become a history bypass). Items are marked
-     *  `historical` (catch-up framing). `droppedChannels` names channels whose earliest retained
-     *  message postdates the focus-watermark — older ambient may have aged out of the per-channel
-     *  window (never-silent). Empty unless in focus. Wildcard subscriptions (`team.>`) are skipped
-     *  (can't Direct-Get a wildcard). */
+     *  channel yields nothing, and is named in `droppedChannels` — recall must not become a history
+     *  bypass, and it must not claim a suppressed channel's window was empty and complete either).
+     *  Items are marked `historical` (catch-up framing). `droppedChannels` also names channels whose
+     *  earliest retained message postdates the focus-watermark — older ambient may have aged out of
+     *  the per-channel window — and wildcard subscriptions (`team.>`), which recall cannot read back
+     *  per concrete sub-channel (#977: a wildcard join is not itself a channel ingest can consult a
+     *  replay policy for) and so cannot vouch for either (never-silent throughout). Empty unless in
+     *  focus. */
     async recallAmbient() {
         if (this._attention !== "focus" || this.focusSince === undefined)
             return { items: [], droppedChannels: [] };
         const items = [];
         const droppedChannels = [];
         for (const channel of this.ep.joinedChannels()) {
-            if (!isConcreteChannel(channel))
+            if (!isConcreteChannel(channel)) {
+                droppedChannels.push(channel);
                 continue;
+            }
             if (this.focusRecallUnsafeChannels.has(channel)) {
                 droppedChannels.push(channel);
                 continue;
@@ -949,6 +1017,30 @@ export class MeshAgent extends EventEmitter {
             this.assertKnownMentions(clean);
         return this.ep.multicast(text, { channel, mentions: clean, contextId: this._contextId });
     }
+    /**
+     * What a caller can TELL about a send target BEFORE the publish: whether the name
+     * already existed (joined, registry, or prior traffic) and close matches when it
+     * did not. Does not refuse create. Graded before multicast so the new message cannot
+     * make the name look pre-existing.
+     */
+    async describeSendChannel(channel) {
+        if (this.ep.getChannelConfig(channel))
+            return "existing channel";
+        const known = new Set(this.ep.joinedChannels().filter(isConcreteChannel));
+        try {
+            for (const row of await this.ep.listChannels())
+                known.add(row.channel);
+        }
+        catch {
+            /* no stream: joined + registry cache still distinguish a typo of a channel we are on */
+        }
+        if (known.has(channel))
+            return "existing channel";
+        const hints = closeChannelNames(channel, [...known]);
+        if (hints.length)
+            return `new channel - no registry entry and no prior traffic; did you mean ${hints.map((h) => "#" + h).join(", ")}?`;
+        return "new channel - no registry entry and no prior traffic";
+    }
     /** Throw if any name isn't a peer we've observed. Validates against the FULL roster
      *  (incl. self — your own name is a valid participant; resolvePeer's self-filter would
      *  wrongly reject it), case-insensitively. Send is all-or-nothing: one unknown @name aborts
@@ -980,10 +1072,9 @@ export class MeshAgent extends EventEmitter {
         return { msg, peer };
     }
     // ---- supervision ---------------------------------------------------------
-    /** Ask the manager to spawn a new teammate into this space (its `start` op).
-     *  #159 B1: the manager replies to `start` only on a REAL outcome — presence join, process exit,
-     *  or its ~30s readiness backstop — so the request must outlive that window ({@link SPAWN_TIMEOUT_MS}),
-     *  not the 5s op default.
+    /** Ask the manager to spawn a new teammate into this space (its `spawn` action).
+     *  The request uses {@link SPAWN_TIMEOUT_MS} as its floor; after acceptance, core follows through
+     *  the exact connector-selected readiness budget carried by the acceptance.
      *  How it lands — a detached PTY, a tmux window, a cmux tab — is the manager's
      *  runtime; from here it just joins the mesh as a lateral peer. `opts.agent` picks
      *  the harness (default the manager's `COTAL_DEFAULT_AGENT`, else `cotal`/Claude), `opts.model` /
@@ -995,10 +1086,63 @@ export class MeshAgent extends EventEmitter {
      *  operator-local intent, kept off the peer-facing spawn door — see #159.) */
     async spawn(name, role, opts) {
         await this.requireConnected();
-        const args = { name, role, agent: opts?.agent, model: opts?.model, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt };
+        const raw = opts?.model;
+        if (raw !== undefined && !raw.trim())
+            return { ok: false, error: "model: must not be empty" };
+        const requested = raw?.trim();
+        const args = { name, role, agent: opts?.agent, model: requested || undefined, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt };
         // P2 item 2 (2b): spawn is an ACTION — follow the acceptance to the terminal so cotal_spawn
         // stays synchronous (the MCP reply carries the live outcome, not the pre-launch acceptance).
-        return this.managerInvoke("spawn", args, { deadlineMs: SPAWN_TIMEOUT_MS, follow: true });
+        const reply = await this.managerInvoke("spawn", args, { deadlineMs: SPAWN_TIMEOUT_MS, follow: true });
+        if (!requested)
+            return reply;
+        // A requested pin that the manager did not record is the silent-drop failure (#972): the spawn
+        // looks successful, the seat comes up on the harness default, and nothing in the spawn result
+        // names the mismatch. Inspect is the manager's recorded pin (persona file or this override).
+        // A wait-timeout is still a timeout, not evidence the pin landed — annotate it, never upgrade it.
+        const actual = reply.data;
+        const seat = actual?.name ?? name;
+        const recorded = await this.inspectModel(seat);
+        const recordedLabel = !recorded.ok
+            ? `could not inspect the recorded pin: ${recorded.error}`
+            : recorded.model === undefined
+                ? "the manager recorded no model pin"
+                : `the manager recorded ${JSON.stringify(recorded.model)}`;
+        if (recorded.ok && recorded.model !== requested) {
+            return {
+                ok: false,
+                error: `requested model ${JSON.stringify(requested)} but ${recordedLabel} for "${seat}" — refusing a spawn whose pin did not land. The seat may already be live; inspect it before retrying, because a retry duplicates the spawn`,
+            };
+        }
+        if (!reply.ok) {
+            return {
+                ok: false,
+                error: `${reply.error ?? "manager refused"} (requested model ${JSON.stringify(requested)}; ${recordedLabel} for "${seat}")`,
+            };
+        }
+        if (!recorded.ok) {
+            return {
+                ok: false,
+                error: `requested model ${JSON.stringify(requested)} for "${seat}" but ${recordedLabel} — refusing to report a pin that cannot be audited`,
+            };
+        }
+        return {
+            ok: true,
+            data: { ...reply.data, model: recorded.model },
+        };
+    }
+    /** The manager's recorded model pin for a managed seat (`inspect.model`). Absence is a real
+     *  state: a launch may pin none. Distinct from a failed inspect, which cannot attest. */
+    async inspectModel(name) {
+        const info = await this.managerInvoke("inspect", { name });
+        if (!info.ok)
+            return { ok: false, error: info.error ?? "inspect refused" };
+        const model = info.data?.model;
+        if (model === undefined)
+            return { ok: true };
+        if (typeof model !== "string")
+            return { ok: false, error: `inspect returned a non-string model for "${name}"` };
+        return { ok: true, model };
     }
     /** One v0.4 manager-endpoint invoke (P2 item 1, 1c.2b): the generic {@link CotalEndpoint.invokeService}
      *  path (describe → §13.7 store fetch → digest-verified recompile → typed command), adapted back to
@@ -1029,12 +1173,19 @@ export class MeshAgent extends EventEmitter {
                     ok: false,
                     error: unansweredRequest(e)
                         ? `${e.message} (no responder answered - a manager may be down, or this credential holds no "${command}" capability and the broker denied the request)`
-                        : `${e.code}: ${e.message}`,
+                        : renderLifecycleBlocked(`${e.code}: ${e.message}`, e),
+                    ...(e.details ? { details: e.details } : {}),
                 };
             return { ok: false, error: e.message };
         }
-        if (r.reply.ok !== true)
-            return { ok: false, error: r.reply.error?.message ?? r.reply.error?.code ?? "error" };
+        if (r.reply.ok !== true) {
+            const raw = r.reply.error?.message ?? r.reply.error?.code ?? "error";
+            return {
+                ok: false,
+                error: renderLifecycleBlocked(raw, r.reply.error),
+                ...(r.reply.error?.details ? { details: r.reply.error.details } : {}),
+            };
+        }
         return { ok: true, ...(r.reply.data !== undefined ? { data: r.reply.data } : {}) };
     }
     /** Resolve a managed agent's CURRENT principal triple (owner-mode targets are (owner, actor,
@@ -1158,6 +1309,17 @@ export class MeshAgent extends EventEmitter {
         }
         return reply;
     }
+    /** Mesh-side persona catalog list: name, role, model, description, scoped by the same
+     *  ownership rule as `definePersona`. */
+    async listPersonas() {
+        await this.requireConnected();
+        return this.managerInvoke("list-personas", undefined);
+    }
+    /** Mesh-side persona catalog show of one card. Unauthorized / missing names are not-found. */
+    async showPersona(name) {
+        await this.requireConnected();
+        return this.managerInvoke("show-persona", { name });
+    }
     // ---- presence ------------------------------------------------------------
     /** The full roster, including ourselves. */
     roster() {
@@ -1207,6 +1369,7 @@ export class MeshAgent extends EventEmitter {
             description: cfg?.description,
             instructions: cfg?.instructions,
             replay: this.ep.channelReplay(channel),
+            registered: cfg !== undefined,
         };
     }
     /** Channels we're currently subscribed to (live — reflects join/leave). */
@@ -1348,23 +1511,72 @@ export class MeshAgent extends EventEmitter {
      * attached Codex TUI. Consumer names are generated per reset, so normalize them before
      * deduplicating; otherwise every `_71`, `_72`, ... would look like a new fault. */
     handleEndpointError(error) {
+        // connectionIssue is the bounded readiness diagnostic documented above: retain failures only
+        // while the endpoint has not bound. Post-bind consumer/permission faults are still logged, but
+        // presenting one as the current connection failure after readiness succeeded is stale and false.
+        if (!this._connected && !this._stopping)
+            this.lastConnectionError = error.message;
+        this.logEndpointNotice("error", error);
+    }
+    handleEndpointWarning(error) {
+        this.logEndpointNotice("warning", error);
+    }
+    logEndpointNotice(kind, error) {
         const now = Date.now();
-        this.lastConnectionError = error.message;
         const fingerprint = error.message.replace(/oc_[A-Za-z0-9]+_\d+/g, "oc_*");
-        const prior = this.endpointErrorLog.get(fingerprint);
+        const prior = this.endpointNoticeLog.get(fingerprint);
         if (prior && now - prior.lastLoggedAt < ENDPOINT_ERROR_LOG_WINDOW_MS) {
             prior.suppressed++;
             return;
         }
         const suffix = prior?.suppressed ? ` (${prior.suppressed} repeats suppressed)` : "";
-        this.endpointErrorLog.set(fingerprint, { lastLoggedAt: now, suppressed: 0 });
+        this.endpointNoticeLog.set(fingerprint, { lastLoggedAt: now, suppressed: 0 });
         // Bound the map even for a server producing novel error text on every request.
-        if (this.endpointErrorLog.size > 16)
-            this.endpointErrorLog.delete(this.endpointErrorLog.keys().next().value);
-        this.log(`endpoint error: ${error.message}${suffix}`);
+        if (this.endpointNoticeLog.size > 16)
+            this.endpointNoticeLog.delete(this.endpointNoticeLog.keys().next().value);
+        this.log(`endpoint ${kind}: ${error.message}${suffix}`);
     }
     log(msg) {
         process.stderr.write(`[cotal-connector] ${msg}\n`);
     }
 }
+/** Names already known that differ from `channel` by one insertion, deletion, or substitution. */
+export function closeChannelNames(channel, known) {
+    const out = [];
+    for (const name of known) {
+        if (name !== channel && editDistanceAtMostOne(channel, name))
+            out.push(name);
+    }
+    out.sort((a, b) => a.localeCompare(b));
+    return out.slice(0, 3);
+}
+function editDistanceAtMostOne(a, b) {
+    if (a === b)
+        return true;
+    const da = a.length - b.length;
+    if (da > 1 || da < -1)
+        return false;
+    let i = 0;
+    let j = 0;
+    let skipped = false;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        if (skipped)
+            return false;
+        skipped = true;
+        if (a.length > b.length)
+            i++;
+        else if (b.length > a.length)
+            j++;
+        else {
+            i++;
+            j++;
+        }
+    }
+    return true;
+}
 //# sourceMappingURL=agent.js.map