@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/lib/mailbox-gc.js

@@ -0,0 +1,161 @@
+/**
+ * Mailbox liveness sweep and GC.
+ *
+ * A box whose owning agent is no longer alive is a ghost: pending messages will
+ * never be drained, and any feed block tied to that box is stale. This module
+ * archives dead-box messages and prunes old consumed entries so the spool stays
+ * bounded under fleet load.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getMailboxRootDir } from './state.js';
+import { mailboxDir, isValidMailboxId, readMessage, } from './mailbox.js';
+import { listBlocks, removeBlock } from './feed.js';
+const DEFAULT_MAX_CONSUMED_AGE_MINUTES = 24 * 60;
+function consumedAgeMinutes(file, now) {
+    try {
+        const stat = fs.statSync(file);
+        return (now.getTime() - stat.mtimeMs) / 60_000;
+    }
+    catch {
+        return 0;
+    }
+}
+function jsonFiles(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => n.endsWith('.json')).sort();
+}
+function archiveAllPending(boxDir, reason) {
+    let n = 0;
+    for (const dir of [path.join(boxDir, 'inbox'), path.join(boxDir, 'processing')]) {
+        for (const name of jsonFiles(dir)) {
+            const src = path.join(dir, name);
+            const dest = path.join(boxDir, 'consumed', name);
+            try {
+                const msg = readMessage(src);
+                if (msg) {
+                    msg.dropped = reason;
+                    const tmp = `${dest}.${process.pid}.tmp`;
+                    fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
+                    fs.renameSync(tmp, dest);
+                    fs.unlinkSync(src);
+                }
+                else {
+                    fs.renameSync(src, dest);
+                }
+                n++;
+            }
+            catch {
+                // ignore racing writers
+            }
+        }
+    }
+    return n;
+}
+function pruneConsumed(boxDir, maxAgeMinutes, now) {
+    let n = 0;
+    const consumed = path.join(boxDir, 'consumed');
+    for (const name of jsonFiles(consumed)) {
+        const file = path.join(consumed, name);
+        if (consumedAgeMinutes(file, now) >= maxAgeMinutes) {
+            try {
+                fs.unlinkSync(file);
+                n++;
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return n;
+}
+/**
+ * Sweep all mailboxes. For dead boxes (not in `activeBoxIds`), archive every
+ * pending message as `dropped: dead` and remove any feed block tied to that
+ * mailbox. For live boxes, drop expired messages and prune old consumed files.
+ */
+export function gcMailbox(activeBoxIds, options = {}) {
+    const root = options.root ?? getMailboxRootDir();
+    const feedRoot = options.feedRoot;
+    const now = options.now ?? new Date();
+    const maxConsumedAgeMinutes = options.maxConsumedAgeMinutes ?? DEFAULT_MAX_CONSUMED_AGE_MINUTES;
+    const result = {
+        boxesScanned: 0,
+        deadBoxes: 0,
+        messagesDroppedExpired: 0,
+        messagesDroppedDead: 0,
+        consumedPruned: 0,
+        blocksRemoved: 0,
+    };
+    let boxNames;
+    try {
+        boxNames = fs.readdirSync(root);
+    }
+    catch {
+        return result;
+    }
+    // Pre-compute dead blocks so we remove each once, regardless of how many
+    // messages reference it.
+    const blocksToRemove = new Set();
+    for (const block of listBlocks(feedRoot)) {
+        if (!activeBoxIds.has(block.mailboxId)) {
+            blocksToRemove.add(block.blockId);
+        }
+    }
+    for (const name of boxNames) {
+        if (!isValidMailboxId(name))
+            continue;
+        result.boxesScanned++;
+        const boxDir = mailboxDir(name, root);
+        if (!activeBoxIds.has(name)) {
+            result.deadBoxes++;
+            result.messagesDroppedDead += archiveAllPending(boxDir, 'dead');
+            result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
+            // Also prune the empty box dir if it is now empty.
+            try {
+                for (const sub of ['inbox', 'processing', 'consumed']) {
+                    const subdir = path.join(boxDir, sub);
+                    if (fs.existsSync(subdir) && fs.readdirSync(subdir).length === 0) {
+                        fs.rmdirSync(subdir);
+                    }
+                }
+                if (fs.existsSync(boxDir) && fs.readdirSync(boxDir).length === 0) {
+                    fs.rmdirSync(boxDir);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        else {
+            // Live box: lazy expiry is handled by drain/peek, but sweep here for GC metrics.
+            // We still need to read expired messages; reuse readMessage directly to avoid
+            // importing sweepExpired and duplicating logic.
+            for (const sub of ['inbox', 'processing']) {
+                const dir = path.join(boxDir, sub);
+                for (const file of jsonFiles(dir)) {
+                    const msg = readMessage(path.join(dir, file));
+                    if (msg && msg.expiresAt) {
+                        const ts = Date.parse(msg.expiresAt);
+                        if (!Number.isNaN(ts) && ts <= now.getTime()) {
+                            result.messagesDroppedExpired++;
+                        }
+                    }
+                }
+            }
+            result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
+        }
+    }
+    for (const blockId of blocksToRemove) {
+        if (removeBlock(blockId, feedRoot)) {
+            result.blocksRemoved++;
+        }
+    }
+    return result;
+}

package/dist/lib/mailbox.d.ts

@@ -8,8 +8,21 @@ export interface MailboxMessage {
     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;
+    /**
+     * 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
@@ -31,7 +44,18 @@ export declare function enqueue(boxDir: string, msg: {
     to: string;
     text: string;
     from?: string;
+    blockId?: 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.
+ */
+export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date): 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
@@ -40,8 +64,8 @@ export declare function enqueue(boxDir: string, msg: {
  *
  * `boxId` defaults to the box's directory name — the id it was created under.
  */
-export declare function drain(boxDir: string, boxId?: string): MailboxMessage[];
+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): MailboxMessage[];
+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;

package/dist/lib/mailbox.js

@@ -19,6 +19,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { getMailboxRootDir } from './state.js';
+import { recordMessageReceipt } from './feed.js';
 /**
  * A mailboxId must be a single, separator-free path segment. Real ids (session
  * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
@@ -68,13 +69,18 @@ export function enqueue(boxDir, msg) {
     assertValidMailboxId(msg.to);
     ensureDirs(boxDir);
     const msgId = newMsgId();
+    const now = new Date();
     const record = {
         msgId,
         to: msg.to,
         from: msg.from,
-        ts: new Date().toISOString(),
+        ts: now.toISOString(),
         text: msg.text,
+        blockId: msg.blockId,
     };
+    if (msg.ttlSeconds != null && msg.ttlSeconds > 0) {
+        record.expiresAt = new Date(now.getTime() + msg.ttlSeconds * 1000).toISOString();
+    }
     const target = path.join(inboxDir(boxDir), `${msgId}.json`);
     const tmp = `${target}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf-8');
@@ -82,7 +88,7 @@ export function enqueue(boxDir, msg) {
     return msgId;
 }
 /** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
-function readMessage(file) {
+export function readMessage(file) {
     let raw;
     try {
         raw = fs.readFileSync(file, 'utf-8');
@@ -101,7 +107,62 @@ function readMessage(file) {
     if (typeof m?.msgId !== 'string' || typeof m?.to !== 'string' || typeof m?.text !== 'string') {
         return null;
     }
-    return { msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text };
+    return { msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text, expiresAt: m.expiresAt, blockId: m.blockId, 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;
+    const ts = Date.parse(msg.expiresAt);
+    return !Number.isNaN(ts) && ts <= now.getTime();
+}
+function archiveDropped(boxDir, name, reason) {
+    const src = path.join(inboxDir(boxDir), name);
+    const dest = path.join(consumedDir(boxDir), name);
+    try {
+        const msg = readMessage(src);
+        if (msg) {
+            msg.dropped = reason;
+            fs.writeFileSync(`${dest}.tmp`, JSON.stringify(msg, null, 2), 'utf-8');
+            fs.renameSync(`${dest}.tmp`, dest);
+            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.
+ */
+export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date()) {
+    ensureDirs(boxDir);
+    let n = 0;
+    for (const dir of [inboxDir(boxDir), processingDir(boxDir)]) {
+        for (const name of jsonFiles(dir)) {
+            const msg = readMessage(path.join(dir, name));
+            if (msg && msg.to === boxId && isExpired(msg, now)) {
+                try {
+                    const dest = path.join(consumedDir(boxDir), name);
+                    msg.dropped = 'expired';
+                    const tmp = `${dest}.${process.pid}.tmp`;
+                    fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
+                    fs.renameSync(tmp, dest);
+                    fs.unlinkSync(path.join(dir, name));
+                    n++;
+                }
+                catch {
+                    // ignore racing claimers
+                }
+            }
+        }
+    }
+    return n;
 }
 function jsonFiles(dir) {
     let names;
@@ -118,6 +179,9 @@ function jsonFiles(dir) {
  * 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);
@@ -131,6 +195,15 @@ function consumeClaimed(boxDir, name, expectedTo) {
     }
     if (!msg || msg.to !== expectedTo)
         return null; // dropped (corrupt or wrong box)
+    if (msg.blockId) {
+        try {
+            const feedRoot = process.env.AGENTS_FEED_DIR;
+            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: 'consumed', at: new Date().toISOString(), from: msg.from }, feedRoot);
+        }
+        catch {
+            // Receipt surfacing is best-effort; never stall delivery.
+        }
+    }
     return msg;
 }
 /**
@@ -141,8 +214,9 @@ function consumeClaimed(boxDir, name, expectedTo) {
  *
  * `boxId` defaults to the box's directory name — the id it was created under.
  */
-export function drain(boxDir, boxId = path.basename(boxDir)) {
+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))) {
@@ -167,7 +241,8 @@ export function drain(boxDir, boxId = path.basename(boxDir)) {
     return out;
 }
 /** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
-export function peek(boxDir, boxId = path.basename(boxDir)) {
+export function peek(boxDir, boxId = path.basename(boxDir), now = new Date()) {
+    sweepExpired(boxDir, boxId, now);
     const out = [];
     for (const dir of [processingDir(boxDir), inboxDir(boxDir)]) {
         for (const name of jsonFiles(dir)) {

package/dist/lib/mcp.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
+import * as os from 'os';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
 import { IS_WINDOWS, needsWindowsShell } from './platform/index.js';
@@ -287,6 +288,26 @@ export async function registerMcpCommandToTargets(targets, name, commandSpec, sc
 function registerMcpCommand(agentId, name, commandSpec, scope, transport, options = {}) {
     try {
         validateMcpServerName(name);
+        if (agentId === 'hermes' || agentId === 'forge') {
+            const server = {
+                name,
+                path: '',
+                config: {
+                    name,
+                    transport: transport === 'http' ? 'http' : 'stdio',
+                    ...(transport === 'http'
+                        ? { url: commandSpec.command }
+                        : { command: commandSpec.command, args: commandSpec.args }),
+                },
+            };
+            if (agentId === 'hermes') {
+                installMcpToHermesConfig(server, options.home || os.homedir());
+            }
+            else {
+                installMcpToForgeConfig(server, options.home || os.homedir());
+            }
+            return { success: true };
+        }
         const bin = options.binary || AGENTS[agentId].cliCommand;
         const commandArgs = [commandSpec.command, ...commandSpec.args];
         const args = agentId === 'claude'
@@ -410,6 +431,59 @@ function installMcpToFactoryConfig(server, versionHome) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+function installMcpToHermesConfig(server, versionHome) {
+    const configPath = path.join(versionHome, '.hermes', 'config.yaml');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            config = parsed;
+        }
+    }
+    if (!config.mcp_servers || typeof config.mcp_servers !== 'object' || Array.isArray(config.mcp_servers)) {
+        config.mcp_servers = {};
+    }
+    const mcpServers = config.mcp_servers;
+    if (server.config.transport === 'stdio') {
+        mcpServers[server.name] = {
+            command: server.config.command,
+            args: server.config.args || [],
+            ...(server.config.env && { env: server.config.env }),
+        };
+    }
+    else {
+        mcpServers[server.name] = {
+            url: server.config.url,
+        };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
+}
+function installMcpToForgeConfig(server, versionHome) {
+    const configPath = path.join(versionHome, '.forge', '.mcp.json');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object' || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    const mcpServers = config.mcpServers;
+    if (server.config.transport === 'stdio') {
+        mcpServers[server.name] = {
+            command: server.config.command,
+            args: server.config.args || [],
+            ...(server.config.env && { env: server.config.env }),
+        };
+    }
+    else {
+        mcpServers[server.name] = {
+            url: server.config.url,
+        };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
 function installMcpToOpenCodeConfig(server, versionHome) {
     const configPath = path.join(versionHome, '.opencode', 'opencode.jsonc');
     let config = {};
@@ -505,6 +579,14 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 installMcpToFactoryConfig(server, versionHome);
                 applied.push(server.name);
             }
+            else if (agentId === 'hermes') {
+                installMcpToHermesConfig(server, versionHome);
+                applied.push(server.name);
+            }
+            else if (agentId === 'forge') {
+                installMcpToForgeConfig(server, versionHome);
+                applied.push(server.name);
+            }
         }
         catch (err) {
             const message = err.message;

package/dist/lib/memory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Canonical agent memory resource — accumulated facts/preferences/knowledge
+ * distinct from `rules` (instructions / AGENTS.md persona).
+ *
+ * Layout (project > user > system layering):
+ *   ~/.agents/memory/MEMORY.md          always-read index
+ *   ~/.agents/memory/<slug>.md          individual facts
+ *   ~/.agents/.system/memory/           system layer
+ *   <project>/.agents/memory/           project layer
+ *
+ * Sync fans out into each capable agent's version home under an agent-specific
+ * target dir (see memoryTargetDir).
+ */
+import type { AgentId } from './types.js';
+export interface MemoryFact {
+    /** Filename without .md (slug). */
+    name: string;
+    /** Absolute path to the fact file. */
+    path: string;
+    /** Layer that wins for this name. */
+    layer: 'project' | 'user' | 'system';
+    /** First non-empty line of the body (for list display). */
+    summary: string;
+}
+export interface MemoryLayerDir {
+    layer: 'project' | 'user' | 'system';
+    dir: string;
+}
+/** User-layer memory root (~/.agents/memory/). */
+export declare function getUserMemoryDir(): string;
+/** System-layer memory root (~/.agents/.system/memory/). */
+export declare function getSystemMemoryDir(): string;
+/** Project-layer memory root when a project agents dir exists. */
+export declare function getProjectMemoryDir(cwd?: string): string | null;
+/** Ensure the user memory dir exists (creates MEMORY.md index if missing). */
+export declare function ensureUserMemoryDir(): string;
+/** Layer dirs highest-priority first. */
+export declare function getMemoryLayerDirs(cwd?: string): MemoryLayerDir[];
+/** List memory facts with project > user > system override on name. */
+export declare function listMemoryFacts(cwd?: string): MemoryFact[];
+/** Read one fact by name (winning layer). */
+export declare function readMemoryFact(name: string, cwd?: string): MemoryFact | null;
+/** Write a fact into the user layer. Returns the absolute path. */
+export declare function addMemoryFact(name: string, body: string): string;
+/** Remove a fact from the user layer. Returns true if a file was deleted. */
+export declare function removeMemoryFact(name: string): boolean;
+/** Rebuild MEMORY.md index from sibling fact files in a single layer dir. */
+export declare function rebuildMemoryIndex(dir: string): void;
+/**
+ * Per-agent target directory (relative to version home) for synced memory.
+ * Claude/Codex/OpenClaw/Grok get native-ish paths; others get a generic memory/.
+ */
+export declare function memoryTargetDir(agent: AgentId): string;
+/** Copy canonical layered memory into one version home. Returns fact names written. */
+export declare function syncMemoryToVersionHome(agent: AgentId, versionHome: string, cwd?: string): string[];