@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/mailbox-target.js

@@ -1,33 +1,19 @@
 import { sessionHeadline } from './session/title.js';
-/**
- * The mailbox id a live session's box is keyed by. Teams stamp a durable
- * `agentId` (== the Claude session id for Claude teammates); a bare run has
- * only its `sessionId`. The spawn-time `AGENTS_MAILBOX_DIR` wiring must key the
- * box by this same id — this is the single source of truth for both sides.
- */
 export function mailboxIdForActiveSession(s) {
     return s.agentId ?? s.sessionId;
 }
 function labelFor(s) {
     return sessionHeadline(s) ?? s.teamName ?? s.host ?? s.context;
 }
-/**
- * Resolve `target` against the live sessions. Exact id matches win over prefix
- * matches; results are de-duped by canonical mailbox id (collapsed subagents
- * share one). `isCloudTask` is consulted first so a cloud task id routes to the
- * cloud provider.
- */
 export function resolveMessageTarget(target, sessions, isCloudTask) {
     if (isCloudTask(target))
         return { kind: 'cloud', id: target };
-    // An empty target would make every `startsWith` prefix match — never guess.
     if (target.length === 0)
         return { kind: 'none' };
     const exact = sessions.filter((s) => s.sessionId === target || s.agentId === target);
     const chosen = exact.length > 0
         ? exact
         : sessions.filter((s) => Boolean(s.sessionId?.startsWith(target)) || Boolean(s.agentId?.startsWith(target)));
-    // De-dupe by canonical mailbox id (one box per logical agent).
     const byId = new Map();
     for (const s of chosen) {
         const id = mailboxIdForActiveSession(s);
@@ -44,19 +30,6 @@ export function resolveMessageTarget(target, sessions, isCloudTask) {
         candidates: [...byId.entries()].map(([id, s]) => ({ id, label: labelFor(s) })),
     };
 }
-/**
- * Decide how `agents message <target>` should handle a target that matched no
- * local/cloud session (RUSH-2366 follow-up): `getActiveSessions()` has no
- * visibility into a detached `agents run --device <host> --no-follow`
- * dispatch, whose only local record is the `~/.agents/.cache/hosts/<id>.json`
- * sidecar `agents devices ps` reads. Pure — the caller does the actual lookup
- * (`resolveTaskRef`) and I/O (the ssh reroute).
- *
- * `remoteRef` prefers the remote agent's OWN identity (its captured session id
- * or `--name` handle) over the LOCAL dispatch-record id the user typed here —
- * the live process on the host registers itself under the former, never the
- * latter.
- */
 export function decideHostTaskRoute(task, target) {
     if (!task)
         return { kind: 'not-found' };

package/dist/lib/mailbox.d.ts

@@ -1,59 +1,20 @@
-/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
 export declare const DEFAULT_TTL_SECONDS: number;
-/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
 export declare const MAILBOX_TTL_ENV = "AGENTS_MAILBOX_TTL";
-/** A single mailbox message. `text` may embed `host:/path` clip tokens. */
 export interface MailboxMessage {
-    /** Unique, time-sortable id. Also the on-disk filename stem. */
     msgId: string;
-    /** The mailboxId this message is addressed to (anti-misroute stamp). */
     to: string;
-    /** Who sent it (operator label / agent id / host). Optional. */
     from?: string;
-    /** ISO-8601 creation time. */
     ts: string;
-    /** Optional ISO-8601 expiry time. Expired messages are dropped, not delivered. */
     expiresAt?: string;
-    /** The message body. */
     text: string;
-    /**
-     * The feed block this message answers. Set by `agents message` when the
-     * target has an open block, so the drain can surface consumed/continued
-     * receipts back to the feed store.
-     */
     blockId?: string;
-    /**
-     * Which ASK of that block this message answers, and which claim sent it. A
-     * blockId is per SESSION and is reused by every generation of that session's
-     * questions, so without these a `consumed` receipt raised on drain cannot say
-     * WHICH question it acknowledges -- and a late one for question N would
-     * resolve question N+1 (PHNX-3999). Carried on the message so the binding
-     * survives the process that enqueued it.
-     */
     generation?: string;
     attempt?: string;
-    /**
-     * Drop reason when a message is archived without delivery (expired, dead box, etc.).
-     * Set by the TTL/liveness layer, not by writers.
-     */
     dropped?: string;
 }
-/**
- * A mailboxId must be a single, separator-free path segment. Real ids (session
- * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
- * else fails loud instead of silently misrouting — a message whose id contained
- * a `/` would nest under a different dir than the `to` stamp it is matched
- * against, and would be dropped with no error. Also blocks `.`/`..` traversal
- * once `agents message` starts accepting external target ids.
- */
 export declare function isValidMailboxId(mailboxId: string): boolean;
 export declare function assertValidMailboxId(mailboxId: string): void;
-/** Absolute path to a box. `root` override is for tests. */
 export declare function mailboxDir(mailboxId: string, root?: string): string;
-/**
- * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
- * is stamped so a drain can refuse a message that lands in the wrong box.
- */
 export declare function enqueue(boxDir: string, msg: {
     to: string;
     text: string;
@@ -63,38 +24,16 @@ export declare function enqueue(boxDir: string, msg: {
     attempt?: string;
     ttlSeconds?: number;
 }): string;
-/** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
 export declare function readMessage(file: string): MailboxMessage | null;
-/** True when a message has a parsed expiry in the past. */
 export declare function isExpired(msg: MailboxMessage, now?: Date): boolean;
-/**
- * Move expired messages from inbox/ and processing/ into consumed/ with a
- * `dropped: expired` marker. Called by drain/peek before returning messages.
- *
- * When a dropped message carries a `blockId`, a failure receipt is surfaced
- * back to the feed store so the sender sees the bounce.
- */
 export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date, feedRoot?: string): number;
-/**
- * Drain the box: return every pending message addressed to it, in FIFO order,
- * removing them from the queue. Claim-first (inbox → processing → consumed) so
- * an interrupted drain is recovered on the next call (at-least-once). Corrupt
- * files and messages addressed to a different box are dropped, not returned.
- *
- * `boxId` defaults to the box's directory name — the id it was created under.
- */
 export declare function drain(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
-/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
 export declare function peek(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
-/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
 export declare function clear(boxDir: string): number;
-/** Which bucket a stored message currently sits in. */
 export type MailboxState = 'inbox' | 'processing' | 'consumed';
-/** A message read back from a box, tagged with the bucket it was found in. */
 export interface StoredMessage extends MailboxMessage {
     state: MailboxState;
 }
-/** A stored message enriched with the mailbox identity used by comms renderers. */
 export interface CommsMsg {
     from: string;
     to: string;
@@ -104,24 +43,8 @@ export interface CommsMsg {
     state: MailboxState;
     box: string;
 }
-/**
- * Enumerate the box ids under `root` (directory names that are valid mailbox
- * ids). Read-only; does not create the root. Sorted for stable output.
- */
 export declare function listBoxes(root?: string): string[];
-/**
- * Read every message in a box across all three buckets (inbox, processing,
- * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
- * this includes `consumed/` — the delivered history — so callers can surface a
- * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
- * (which is time-sortable), oldest first.
- */
 export declare function readBox(boxDir: string): StoredMessage[];
-/**
- * Poll the complete spool and yield each message once when its box/msgId pair
- * first appears. Existing messages establish the initial baseline unless
- * `backfill` is requested; moving a message between buckets does not re-emit it.
- */
 export declare function watchMessages(root: string, opts: {
     signal?: AbortSignal;
     intervalMs?: number;

package/dist/lib/mailbox.js

@@ -1,35 +1,11 @@
-/**
- * Agent mailbox — a file-spool that lets a message reach an already-running
- * agent mid-flight. One box per logical agent, keyed by a unique-per-launch id
- * (session UUID / teams agentId / loop runId), so boxes are disjoint and a
- * message can never reach the wrong agent (see docs / plan velvety-conjuring-popcorn).
- *
- * Layout: <root>/<mailboxId>/{inbox,processing,consumed}/<msgId>.json
- *   inbox/      pending, written by `agents message`
- *   processing/ claimed by a drain (claim-first = crash-safe)
- *   consumed/   archived after delivery (and dropped mismatches)
- *
- * A box has a SINGLE consumer — the owning agent, whose tool calls (and thus
- * hook-driven drains) are sequential. Writers may be concurrent; each enqueue
- * is atomic (temp-write + rename), so a drain never observes a partial file.
- * Delivery is at-least-once: an interrupted drain leaves the message in
- * processing/, and the next drain recovers it. Consumers dedup by `msgId`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { getMailboxRootDir } from './state.js';
 import { recordMessageReceipt } from './feed/feed.js';
 import { parseDuration } from './hooks/cache.js';
-/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
 export const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
-/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
 export const MAILBOX_TTL_ENV = 'AGENTS_MAILBOX_TTL';
-/**
- * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
- * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
- * fails loud instead of silently disabling expiry.
- */
 function resolveDefaultTtlSeconds() {
     const raw = process.env[MAILBOX_TTL_ENV];
     if (raw == null || raw === '')
@@ -40,14 +16,6 @@ function resolveDefaultTtlSeconds() {
     }
     return parsed;
 }
-/**
- * A mailboxId must be a single, separator-free path segment. Real ids (session
- * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
- * else fails loud instead of silently misrouting — a message whose id contained
- * a `/` would nest under a different dir than the `to` stamp it is matched
- * against, and would be dropped with no error. Also blocks `.`/`..` traversal
- * once `agents message` starts accepting external target ids.
- */
 export function isValidMailboxId(mailboxId) {
     return /^[A-Za-z0-9._-]+$/.test(mailboxId) && mailboxId !== '.' && mailboxId !== '..';
 }
@@ -57,7 +25,6 @@ export function assertValidMailboxId(mailboxId) {
             `matching [A-Za-z0-9._-] (no separators, not '.'/'..').`);
     }
 }
-/** Absolute path to a box. `root` override is for tests. */
 export function mailboxDir(mailboxId, root = getMailboxRootDir()) {
     assertValidMailboxId(mailboxId);
     return path.join(root, mailboxId);
@@ -65,26 +32,16 @@ export function mailboxDir(mailboxId, root = getMailboxRootDir()) {
 function inboxDir(boxDir) { return path.join(boxDir, 'inbox'); }
 function processingDir(boxDir) { return path.join(boxDir, 'processing'); }
 function consumedDir(boxDir) { return path.join(boxDir, 'consumed'); }
-/** Create the three sub-buckets. Idempotent. */
 function ensureDirs(boxDir) {
     fs.mkdirSync(inboxDir(boxDir), { recursive: true });
     fs.mkdirSync(processingDir(boxDir), { recursive: true });
     fs.mkdirSync(consumedDir(boxDir), { recursive: true });
 }
 let seq = 0;
-/**
- * `<epochMs>-<seq>-<rand>` — sorts by filename in FIFO order. The per-process
- * monotonic `seq` breaks ties within the same millisecond (so a single writer's
- * order is preserved); `rand` keeps it unique across processes/hosts.
- */
 function newMsgId() {
     const s = String(seq++).padStart(6, '0');
     return `${Date.now()}-${s}-${randomUUID().slice(0, 8)}`;
 }
-/**
- * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
- * is stamped so a drain can refuse a message that lands in the wrong box.
- */
 export function enqueue(boxDir, msg) {
     assertValidMailboxId(msg.to);
     ensureDirs(boxDir);
@@ -107,10 +64,9 @@ export function enqueue(boxDir, msg) {
     const target = path.join(inboxDir(boxDir), `${msgId}.json`);
     const tmp = `${target}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf-8');
-    fs.renameSync(tmp, target); // atomic on a single filesystem
+    fs.renameSync(tmp, target);
     return msgId;
 }
-/** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
 export function readMessage(file) {
     let raw;
     try {
@@ -130,16 +86,12 @@ export function readMessage(file) {
     if (typeof m?.msgId !== 'string' || typeof m?.to !== 'string' || typeof m?.text !== 'string') {
         return null;
     }
-    // Field-by-field on purpose (an unknown key from a foreign writer is dropped),
-    // so EVERY field the receipt binding depends on must be listed here or it is
-    // silently lost on read and the binding it enables never fires.
     return {
         msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text,
         expiresAt: m.expiresAt, blockId: m.blockId, generation: m.generation, attempt: m.attempt,
         dropped: m.dropped,
     };
 }
-/** True when a message has a parsed expiry in the past. */
 export function isExpired(msg, now = new Date()) {
     if (!msg.expiresAt)
         return false;
@@ -158,21 +110,12 @@ function archiveDropped(boxDir, name, reason) {
             fs.unlinkSync(src);
         }
         else {
-            // corrupt — just move it out of inbox
             fs.renameSync(src, dest);
         }
     }
     catch {
-        // best-effort
     }
 }
-/**
- * Move expired messages from inbox/ and processing/ into consumed/ with a
- * `dropped: expired` marker. Called by drain/peek before returning messages.
- *
- * When a dropped message carries a `blockId`, a failure receipt is surfaced
- * back to the feed store so the sender sees the bounce.
- */
 export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date(), feedRoot) {
     ensureDirs(boxDir);
     let n = 0;
@@ -192,13 +135,11 @@ export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Da
                             recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: 'expired', at: new Date().toISOString(), from: msg.from }, feedRoot ?? process.env.AGENTS_FEED_DIR);
                         }
                         catch {
-                            // Receipt surfacing is best-effort; never stall expiry.
                         }
                     }
                     n++;
                 }
                 catch {
-                    // ignore racing claimers
                 }
             }
         }
@@ -215,15 +156,6 @@ function jsonFiles(dir) {
     }
     return names.filter((n) => n.endsWith('.json')).sort();
 }
-/**
- * Consume a file already sitting in `processing/`: read, verify it is addressed
- * to this box, then archive to `consumed/`. Returns the message iff valid AND
- * addressed here; a mismatched/corrupt file is archived (dropped) so it never
- * loops. Returns null when the file vanished (a racing drain took it).
- *
- * When the message carries a `blockId`, the consumed event is surfaced back to
- * the feed store so the operator can see delivery confirmation.
- */
 function consumeClaimed(boxDir, name, expectedTo) {
     const src = path.join(processingDir(boxDir), name);
     const dest = path.join(consumedDir(boxDir), name);
@@ -232,14 +164,13 @@ function consumeClaimed(boxDir, name, expectedTo) {
         fs.renameSync(src, dest);
     }
     catch {
-        return null; // already archived/claimed elsewhere
+        return null;
     }
     if (!msg || msg.to !== expectedTo)
-        return null; // dropped (corrupt or wrong box)
+        return null;
     if (msg.blockId) {
         try {
             const feedRoot = process.env.AGENTS_FEED_DIR;
-            // The origin rides the message, so the receipt names the ask it answers.
             recordMessageReceipt(msg.blockId, {
                 msgId: msg.msgId, status: 'consumed', at: new Date().toISOString(), from: msg.from,
                 ...(msg.generation !== undefined ? { generation: msg.generation } : {}),
@@ -247,38 +178,27 @@ function consumeClaimed(boxDir, name, expectedTo) {
             }, feedRoot);
         }
         catch {
-            // Receipt surfacing is best-effort; never stall delivery.
         }
     }
     return msg;
 }
-/**
- * Drain the box: return every pending message addressed to it, in FIFO order,
- * removing them from the queue. Claim-first (inbox → processing → consumed) so
- * an interrupted drain is recovered on the next call (at-least-once). Corrupt
- * files and messages addressed to a different box are dropped, not returned.
- *
- * `boxId` defaults to the box's directory name — the id it was created under.
- */
 export function drain(boxDir, boxId = path.basename(boxDir), now = new Date()) {
     ensureDirs(boxDir);
     sweepExpired(boxDir, boxId, now);
     const out = [];
-    // 1. Recover orphans left in processing/ by a prior interrupted drain.
     for (const name of jsonFiles(processingDir(boxDir))) {
         const msg = consumeClaimed(boxDir, name, boxId);
         if (msg)
             out.push(msg);
     }
-    // 2. Claim and consume pending inbox messages.
     for (const name of jsonFiles(inboxDir(boxDir))) {
         const from = path.join(inboxDir(boxDir), name);
         const to = path.join(processingDir(boxDir), name);
         try {
-            fs.renameSync(from, to); // atomic claim
+            fs.renameSync(from, to);
         }
         catch {
-            continue; // vanished — a racing drain took it
+            continue;
         }
         const msg = consumeClaimed(boxDir, name, boxId);
         if (msg)
@@ -286,7 +206,6 @@ export function drain(boxDir, boxId = path.basename(boxDir), now = new Date()) {
     }
     return out;
 }
-/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
 export function peek(boxDir, boxId = path.basename(boxDir), now = new Date()) {
     sweepExpired(boxDir, boxId, now);
     const out = [];
@@ -299,7 +218,6 @@ export function peek(boxDir, boxId = path.basename(boxDir), now = new Date()) {
     }
     return out;
 }
-/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
 export function clear(boxDir) {
     let n = 0;
     for (const name of jsonFiles(inboxDir(boxDir))) {
@@ -308,15 +226,10 @@ export function clear(boxDir) {
             n++;
         }
         catch {
-            // already gone — ignore
         }
     }
     return n;
 }
-/**
- * Enumerate the box ids under `root` (directory names that are valid mailbox
- * ids). Read-only; does not create the root. Sorted for stable output.
- */
 export function listBoxes(root = getMailboxRootDir()) {
     let names;
     try {
@@ -327,13 +240,6 @@ export function listBoxes(root = getMailboxRootDir()) {
     }
     return names.filter((n) => isValidMailboxId(n) && fs.statSync(path.join(root, n)).isDirectory()).sort();
 }
-/**
- * Read every message in a box across all three buckets (inbox, processing,
- * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
- * this includes `consumed/` — the delivered history — so callers can surface a
- * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
- * (which is time-sortable), oldest first.
- */
 export function readBox(boxDir) {
     const out = [];
     const buckets = [
@@ -351,11 +257,6 @@ export function readBox(boxDir) {
     out.sort((a, b) => (a.msgId < b.msgId ? -1 : a.msgId > b.msgId ? 1 : 0));
     return out;
 }
-/**
- * Poll the complete spool and yield each message once when its box/msgId pair
- * first appears. Existing messages establish the initial baseline unless
- * `backfill` is requested; moving a message between buckets does not re-emit it.
- */
 export async function* watchMessages(root, opts) {
     const seen = new Set();
     const requestedInterval = opts.intervalMs ?? 500;
@@ -400,7 +301,6 @@ export async function* watchMessages(root, opts) {
 function compareWatched(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
-/** Wait for the next poll, resolving immediately when the watcher is aborted. */
 function waitForMailboxPoll(intervalMs, signal) {
     if (signal?.aborted)
         return Promise.resolve(false);

package/dist/lib/manifest.d.ts

@@ -1,9 +1,5 @@
 import type { Manifest } from './types.js';
-/** Canonical filename for the manifest in any agents repo or project root. */
 export declare const MANIFEST_FILENAME = "agents.yaml";
-/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export declare function readManifest(repoPath: string): Manifest | null;
-/** Write a Manifest object to agents.yaml in the given directory. */
 export declare function writeManifest(repoPath: string, manifest: Manifest): void;
-/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export declare function createDefaultManifest(): Manifest;

package/dist/lib/manifest.js

@@ -1,33 +1,13 @@
-/**
- * agents.yaml manifest reading, writing, and serialization.
- *
- * The manifest file (agents.yaml) is the central configuration for version defaults,
- * repository overrides, dependencies, and MCP server declarations.
- */
 import * as fs from 'fs';
 import * as yaml from 'yaml';
 import { stringifyDoc } from './yaml-io.js';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { safeJoin } from './paths.js';
-/** Canonical filename for the manifest in any agents repo or project root. */
 export const MANIFEST_FILENAME = 'agents.yaml';
-// Per-path re-entrancy depth so withManifestLock is safe against recursive calls.
 const manifestLockDepth = new Map();
-/** Parse a YAML string into a typed Manifest object. */
 function parseManifest(content) {
     return yaml.parse(content);
 }
-/**
- * Serialize a Manifest to YAML WITHOUT destroying hand-written comments.
- *
- * Plain `yaml.stringify(manifest)` drops every comment, so `agents mcp add`
- * (and every other writeManifest caller) used to clobber annotations in
- * agents.yaml. Matching `serializeCentral` in state.ts: when existing file
- * text is provided, parse it into a `yaml.Document` (comments + key order
- * preserved) and edit only keys that actually changed. Untouched keys and
- * their comments stay byte-stable. Falls back to plain stringify when there
- * is no existing document yet.
- */
 function serializeManifest(manifest, existingContent) {
     const entries = Object.entries(manifest).filter(([, v]) => v !== undefined);
     const isEmpty = entries.length === 0;
@@ -43,8 +23,6 @@ function serializeManifest(manifest, existingContent) {
             changed = true;
         }
     }
-    // Full-document write: callers do read-modify-write, so keys absent from the
-    // new manifest are intentional removals (e.g. clearing beta).
     for (const k of Object.keys(current)) {
         const next = manifest[k];
         if (!(k in manifest) || next === undefined) {
@@ -52,17 +30,10 @@ function serializeManifest(manifest, existingContent) {
             changed = true;
         }
     }
-    // Nothing changed → keep the file byte-identical (comments intact).
     if (!changed)
         return existingContent;
-    // stringifyDoc still normalizes a legacy flow root (`{}`) to block so edited
-    // nodes do not render flow, but no longer forces block on a normal document —
-    // that flattened committed flow sequences and made this writer disagree with
-    // the other agents.yaml writers (RUSH-2505). parseDocument still preserves
-    // comments + key ordering.
     return isEmpty ? '' : stringifyDoc(doc);
 }
-/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export function readManifest(repoPath) {
     const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     if (!fs.existsSync(manifestPath)) {
@@ -82,7 +53,6 @@ function withManifestLock(filePath, fn) {
             manifestLockDepth.set(filePath, depth);
         }
     }
-    // Project manifests are shared (no restricted dir mode unlike ~/.agents).
     ensureLockTarget(filePath);
     return withFileLock(filePath, () => {
         manifestLockDepth.set(filePath, 1);
@@ -94,7 +64,6 @@ function withManifestLock(filePath, fn) {
         }
     });
 }
-/** Write a Manifest object to agents.yaml in the given directory. */
 export function writeManifest(repoPath, manifest) {
     const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     withManifestLock(manifestPath, () => {
@@ -103,20 +72,15 @@ export function writeManifest(repoPath, manifest) {
             existing = fs.readFileSync(manifestPath, 'utf-8');
         }
         catch {
-            /* first write — no file yet (or empty lock target) */
         }
-        // ensureLockTarget may have created an empty file for the lock path.
         if (existing !== null && existing.trim() === '')
             existing = null;
         const content = serializeManifest(manifest, existing);
-        // Skip the atomic rewrite when nothing changed so comments stay byte-stable
-        // and concurrent readers never see a no-op churn.
         if (existing !== null && content === existing)
             return;
         atomicWriteFileSync(manifestPath, content);
     });
 }
-/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export function createDefaultManifest() {
     return {
         agents: {},

package/dist/lib/markdown.d.ts

@@ -1,4 +1 @@
-/**
- * Render markdown content for terminal display.
- */
 export declare function renderMarkdown(content: string): string;

package/dist/lib/markdown.js

@@ -1,16 +1,7 @@
-/**
- * Terminal-aware Markdown rendering using marked and marked-terminal.
- *
- * Provides a single function for converting Markdown content into
- * ANSI-formatted text suitable for terminal output.
- */
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 // @ts-expect-error - marked-terminal types don't match marked's MarkedExtension
 marked.use(markedTerminal());
-/**
- * Render markdown content for terminal display.
- */
 export function renderMarkdown(content) {
     return marked.parse(content);
 }

package/dist/lib/mcp-registry.d.ts

@@ -1,63 +1,14 @@
 import type { AgentId } from './types.js';
-/**
- * On-disk schema of an agent's MCP config file. One entry per distinct
- * serialization, NOT one per agent -- most harnesses share Claude's shape.
- */
-export type McpFormat = 
-/** `{ "mcpServers": { "<name>": {command,args,env} | {url,headers?} } }` */
-'claude-json'
-/** Claude shape, but a remote server is keyed `serverUrl` and has no headers. */
- | 'antigravity-json'
-/** `{ "mcp": { "servers": { "<name>": ... } } }`, remote carries `transport`. */
- | 'openclaw-json'
-/** `{ "mcp": { "<name>": {type:'local',command:[...]} | {type:'remote',url} } }` */
- | 'opencode-jsonc'
-/** `[mcp_servers.<name>]` TOML table. */
- | 'toml'
-/** `mcp_servers:` YAML mapping. */
- | 'yaml'
-/** `{ schema_version, mcp_servers: { "<name>": {transport, ..., enabled} } }` */
- | 'muse-json';
-/** The complete MCP contract for one agent. */
+export type McpFormat = 'claude-json' | 'antigravity-json' | 'openclaw-json' | 'opencode-jsonc' | 'toml' | 'yaml' | 'muse-json';
 interface McpTarget {
-    /** MCP config file under a HOME root (a version home, or the real HOME). */
     home(home: string): string;
-    /** Project-scoped MCP config file for a repo at `cwd`. */
     project(cwd: string): string;
-    /**
-     * Serialization of that file, or `null` when agents-cli cannot yet write this
-     * harness's MCP config. Paths still resolve for the read/detect side.
-     */
     format: McpFormat | null;
-    /** Required when `format` is null: why the write path refuses. */
     unsupportedReason?: string;
-    /**
-     * True when the harness reads this config from the user's REAL home rather
-     * than a per-version home, so `home()` ignores its argument. Callers that
-     * reason about version isolation must check this rather than assuming every
-     * target is version-scoped.
-     */
     homeGlobal?: boolean;
-    /**
-     * When set, `installMcpServers` registers through the harness's own CLI
-     * (`claude mcp add` / `codex mcp add`) instead of writing the file directly.
-     * The path/format above still describe where that CLI lands the entry.
-     */
     cli?: 'claude' | 'codex';
 }
-/**
- * Single source of truth for every MCP-capable agent's config location and
- * format. Keys MUST equal `capableAgents('mcp')` -- pinned by
- * `mcp-registry.test.ts`.
- */
 export declare const MCP_TARGETS: Partial<Record<AgentId, McpTarget>>;
-/** The registry entry for `agent`, or undefined when it stores no MCP config. */
 export declare function mcpTarget(agent: AgentId): McpTarget | undefined;
-/**
- * Why the write path refuses `agent`, or null when it can write.
- *
- * Two distinct refusals, both loud: the agent has no entry at all (not
- * MCP-capable, or a hard-deprecated id), or it has one with `format: null`.
- */
 export declare function mcpWriteUnsupportedReason(agent: AgentId): string | null;
 export {};