macro-agent 0.1.12 → 0.2.1

package/dist/dispatch/mail-inbound-consumer.js

@@ -0,0 +1,360 @@
+/**
+ * Mail-Inbound Consumer
+ *
+ * Receives hub-driven `x-dispatch/work` envelopes from the local agent-inbox
+ * and spawns a worker agent to handle them — without requiring the optional
+ * outbound swarm-dispatch orchestrator (`config.dispatch.enabled`).
+ *
+ * This makes mail-inbound dispatch a **default capability** of macro-agent: as
+ * long as the MAP sidecar is connected and the inbox is running, any hub that
+ * delivers work via `mail/turn.received` will be served.
+ *
+ * ## Data flow
+ *
+ *   hub sends `mail/turn.received`
+ *     → mail-bridge translates {type,body} → {schema,data} + _conversationId
+ *     → inboxAdapter delivers to local inbox (recipient = dispatcherAgentId)
+ *     → inbox.events fires "inbox.message"
+ *     → consumer classifies: schema === 'x-dispatch/work'?
+ *       yes → spawn worker via agentManager.spawn()
+ *            → record agentId → conversationId in side map
+ *     → worker calls done(summary="…SENTINEL…")
+ *     → handlers-v2 stores _lastSummary in agentStore metadata (parentId null branch)
+ *     → agentManager.onLifecycleEvent fires "stopped"
+ *     → consumer reads _lastSummary + conversationId
+ *     → mapSidecar.postMailTurn(conversationId, agentId, summary)  [fire-and-forget]
+ *
+ * @module dispatch/mail-inbound-consumer
+ */
+import { loadoutToSpawnOptions } from "./loadout-translation.js";
+// ─────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Wire the mail-inbound consumer.
+ *
+ * Returns a `stop()` handle that detaches all listeners.
+ * Safe to call multiple times (idempotent cleanup).
+ */
+export function createMailInboundConsumer(opts) {
+    const { dispatcherAgentId, inboxEvents, agentManager, agentStore, getSidecar, getRepoManager, getRepoTransport, log = (msg) => console.log(msg), } = opts;
+    // ── Side-channel maps ────────────────────────────────────────
+    // agentId → conversationId: populated when a worker is spawned for a
+    // mail-inbound envelope; read when the agent's stopped event fires.
+    const agentConversationMap = new Map();
+    // taskId → expiresAt: idempotency guard keyed on the dispatch envelope's
+    // task identifier. The local inbox can re-fire `inbox.message` for the
+    // same logical delivery — without this guard, a single bridged turn would
+    // trigger N concurrent spawn() calls, each producing a long-lived ACP
+    // subprocess.
+    //
+    // Bounded by TTL so the map cannot grow unbounded over a long-running
+    // deployment. SEEN_TASK_TTL_MS is generous (1 hour) — re-deliveries within
+    // that window are dropped, beyond it the dedup expires and a stale retry
+    // could legitimately re-spawn (preferable to permanent memory growth).
+    const SEEN_TASK_TTL_MS = 60 * 60 * 1000;
+    const seenTaskIds = new Map();
+    function pruneSeenTaskIds() {
+        const now = Date.now();
+        for (const [id, expiresAt] of seenTaskIds) {
+            if (expiresAt <= now)
+                seenTaskIds.delete(id);
+        }
+    }
+    // Counter for envelopes dropped because they are malformed (no taskId).
+    // Surfaced via the consumer handle's stats() method so operators can
+    // distinguish "no work" from "work is broken".
+    let droppedMalformedCount = 0;
+    log(`[mail-inbound] Consumer ready — listening for x-dispatch/work envelopes ` +
+        `(recipient=${dispatcherAgentId})`);
+    // ── Pre-spawn repo mount ─────────────────────────────────────
+    // Resolves the worker's cwd from the dispatch envelope's repo metadata.
+    // When clone_policy is 'allowed' and the repo isn't already attached,
+    // clones to clone_path (or a default under cwd) then attaches+declares.
+    // Best-effort: failures log a warning and return undefined (worker
+    // spawns without a repo-specific cwd).
+    async function resolveRepoCwd(repoMeta, taskId) {
+        const manager = getRepoManager?.();
+        if (!manager)
+            return undefined;
+        const canonicalUrl = repoMeta.canonical_url;
+        if (!canonicalUrl)
+            return undefined;
+        // Check if the repo is already attached (by canonical URL match).
+        const existing = manager.list().find((h) => h.identity.canonicalUrl === canonicalUrl);
+        if (existing) {
+            log(`[mail-inbound] Repo already attached at ${existing.localPath} for taskId=${taskId}`);
+            return existing.localPath;
+        }
+        // Not attached — clone only if explicitly allowed.
+        if (repoMeta.clone_policy !== 'allowed') {
+            log(`[mail-inbound] Repo ${canonicalUrl} not attached and clone_policy=${repoMeta.clone_policy ?? 'none'} — ` +
+                `skipping mount for taskId=${taskId}`);
+            return undefined;
+        }
+        const clonePath = repoMeta.clone_path ?? `/tmp/openhive-repos/${repoMeta.repo_id}`;
+        try {
+            const { execSync } = await import("node:child_process");
+            // Clone if the directory doesn't exist yet.
+            const fs = await import("node:fs");
+            if (!fs.existsSync(clonePath)) {
+                log(`[mail-inbound] Cloning ${canonicalUrl} → ${clonePath} for taskId=${taskId}`);
+                execSync(`git clone --depth 1 ${canonicalUrl} ${clonePath}`, {
+                    stdio: "pipe",
+                    timeout: 120_000,
+                });
+            }
+            // Checkout target branch if specified.
+            if (repoMeta.branch) {
+                try {
+                    execSync(`git -C ${clonePath} fetch origin ${repoMeta.branch} --depth 1`, {
+                        stdio: "pipe",
+                        timeout: 60_000,
+                    });
+                    execSync(`git -C ${clonePath} checkout ${repoMeta.branch}`, {
+                        stdio: "pipe",
+                        timeout: 30_000,
+                    });
+                }
+                catch {
+                    log(`[mail-inbound] Branch checkout failed for ${repoMeta.branch} — continuing on default branch`);
+                }
+            }
+            // Attach to the repo manager so future dispatches find it.
+            const handle = await manager.attach({
+                remoteUrl: canonicalUrl,
+                localPath: clonePath,
+                currentBranch: repoMeta.branch,
+            });
+            // Declare the new workspace to the hub (best-effort).
+            const transport = getRepoTransport?.();
+            if (transport) {
+                try {
+                    const bindings = manager.list().map((h) => ({
+                        canonical_url: h.identity.canonicalUrl,
+                        local_path: h.localPath,
+                    }));
+                    await transport.notify("x-workspace/repo.declare", { bindings });
+                }
+                catch {
+                    // Non-fatal — the hub may not support workspace declarations.
+                }
+            }
+            log(`[mail-inbound] Mounted repo at ${handle.localPath} for taskId=${taskId}`);
+            return handle.localPath;
+        }
+        catch (err) {
+            log(`[mail-inbound] Pre-spawn repo mount failed for taskId=${taskId}: ` +
+                `${err.message ?? String(err)}`);
+            return undefined;
+        }
+    }
+    // ── Inbox message listener ───────────────────────────────────
+    const onMessage = (event) => {
+        // Only handle messages delivered to our dispatcher recipient.
+        if (event.agentId !== dispatcherAgentId)
+            return;
+        const content = event.message?.content;
+        if (content?.schema !== "x-dispatch/work")
+            return;
+        const data = content.data;
+        if (!data?.taskId) {
+            droppedMalformedCount++;
+            log(`[mail-inbound] Dropping malformed envelope (no taskId, total=${droppedMalformedCount}) — ` +
+                `keys=${Object.keys(data ?? {}).join(',')} from=${event.message?.sender_id ?? '?'}`);
+            return;
+        }
+        const taskId = data.taskId;
+        pruneSeenTaskIds();
+        const seenExpiresAt = seenTaskIds.get(taskId);
+        if (seenExpiresAt !== undefined && seenExpiresAt > Date.now()) {
+            // Already spawned a worker for this dispatch within the dedup window
+            // — silently ignore the re-delivery. The hub treats dispatch as
+            // exactly-once on the worker side, so dropping is correct.
+            return;
+        }
+        seenTaskIds.set(taskId, Date.now() + SEEN_TASK_TTL_MS);
+        const conversationId = content._conversationId;
+        const prompt = data.prompt ?? data.content ?? "";
+        // Validate the envelope's role against the local role registry. Unknown
+        // role names (e.g. team-role-ref roles like 'executor' surfaced by hubs
+        // that don't share macro-agent's role taxonomy) silently fall back to
+        // GenericRole inside `resolveRole`, which has `lifecycle.type='persistent'`
+        // and no system-prompt instruction to call `done()`. That breaks the
+        // mail-reply path because the worker stops without writing
+        // `_lastSummary`, so we end up logging "Worker stopped but _lastSummary
+        // is empty — no reply turn posted" and the hub never sees the answer.
+        //
+        // Use 'worker' as the fallback (ephemeral lifecycle + LIFECYCLE.DONE
+        // capability + system prompt that mandates `done()`) so unknown roles
+        // get a sensible default that completes the reply round-trip.
+        const requestedRole = data.role;
+        const roleRegistry = agentManager.getRoleRegistry?.();
+        const knownRole = requestedRole && roleRegistry?.getRole(requestedRole) !== undefined;
+        const role = knownRole ? requestedRole : "worker";
+        if (requestedRole && !knownRole) {
+            log(`[mail-inbound] Unknown role '${requestedRole}' for taskId=${taskId} — falling back to 'worker'`);
+        }
+        // Loadout-derived structured fields ride in the envelope. We prefer the
+        // canonical top-level `data.loadout` slot (Step 3 of the ACP+lifecycle
+        // plan) but fall back to the legacy `data.metadata.permissions` shape
+        // for one deprecation cycle so older hubs that haven't rolled the new
+        // wire shape continue to work.
+        //
+        // `loadoutToSpawnOptions` is shared with the new `dispatch/spawn-agent`
+        // MAP handler so both wire paths produce identical spawn options.
+        //
+        // `fullAutonomous: true` because mail-inbound workers have no human in
+        // the loop to answer `ask` rules — collapse them to `allow` (vs. the
+        // safer `deny` default for spawns where a human might still be reached).
+        let wireLoadout = data.loadout;
+        if (!wireLoadout) {
+            const legacyPermissions = data.metadata?.permissions;
+            const legacyMcpProviders = data.metadata?.mcpProviders;
+            if (legacyPermissions || legacyMcpProviders) {
+                wireLoadout = {
+                    ...(legacyPermissions ? { permissions: legacyPermissions } : {}),
+                    ...(legacyMcpProviders ? { mcpProviders: legacyMcpProviders } : {}),
+                };
+            }
+        }
+        const spawnLoadoutOpts = loadoutToSpawnOptions(wireLoadout, {
+            fullAutonomous: true,
+        });
+        // Extract repo metadata from the envelope for pre-spawn mount.
+        const repoMeta = {
+            repo_id: data.metadata?.repo_id,
+            canonical_url: data.metadata?.canonical_url,
+            branch: data.metadata?.branch,
+            commit_sha: data.metadata?.commit_sha,
+            clone_policy: data.metadata?.clone_policy,
+            clone_path: data.metadata?.clone_path,
+        };
+        log(`[mail-inbound] Received x-dispatch/work taskId=${taskId} ` +
+            `conv=${conversationId ?? "(none)"} role=${role}` +
+            (repoMeta.repo_id ? ` repo=${repoMeta.repo_id}` : "") +
+            (spawnLoadoutOpts.permissions
+                ? ` permissions=${JSON.stringify(spawnLoadoutOpts.permissions)}`
+                : ""));
+        // Spawn is async — fire and forget. Errors are logged, not thrown.
+        // Pre-spawn mount resolves the worker's cwd from the repo metadata
+        // before spawning. Best-effort: mount failures proceed without a
+        // repo-specific cwd.
+        (async () => {
+            let repoCwd;
+            if (repoMeta.repo_id) {
+                repoCwd = await resolveRepoCwd(repoMeta, taskId);
+            }
+            const spawned = await agentManager.spawn({
+                task: prompt,
+                task_id: taskId,
+                role,
+                parent: null,
+                // Mail-inbound dispatch workers run sandboxed — strip the host's
+                // user-level Claude setting sources so installed plugin MCP servers
+                // (claude-code-swarm, oh-my-claudecode, …) don't auto-load and hang
+                // session/new on environments where the host services aren't reachable.
+                isolatedSettings: true,
+                ...(repoCwd ? { cwd: repoCwd } : {}),
+                ...spawnLoadoutOpts,
+            });
+            log(`[mail-inbound] Spawned worker agentId=${spawned.id} for taskId=${taskId}` +
+                (repoCwd ? ` cwd=${repoCwd}` : ""));
+            if (conversationId) {
+                agentConversationMap.set(spawned.id, conversationId);
+            }
+            // Spawn only creates an idle ACP session — the task lives in the
+            // system prompt as instructions. To get the model to actually do
+            // the work, send the prompt as a user message via promptUntilDone.
+            // This drives the worker to completion (done() called) so the
+            // lifecycle stopped listener below fires and posts the reply
+            // back to the hub. Fire-and-forget; errors are logged.
+            try {
+                await agentManager.promptUntilDone(spawned.id, prompt, {
+                    maxFollowUps: 0,
+                });
+            }
+            catch (err) {
+                log(`[mail-inbound] promptUntilDone failed for agentId=${spawned.id}: ` +
+                    `${err.message ?? String(err)}`);
+            }
+        })().catch((err) => {
+            log(`[mail-inbound] Spawn failed for taskId=${taskId}: ${err.message ?? String(err)}`);
+        });
+    };
+    inboxEvents.on("inbox.message", onMessage);
+    // ── Lifecycle stopped listener ───────────────────────────────
+    const unsubscribeLifecycle = agentManager.onLifecycleEvent((event) => {
+        if (event.type !== "stopped")
+            return;
+        const agentId = event.agent.id;
+        const conversationId = agentConversationMap.get(agentId);
+        if (!conversationId)
+            return; // not a mail-inbound worker we spawned
+        agentConversationMap.delete(agentId);
+        // Read the summary stored by handlers-v2 for parentless workers.
+        const record = agentStore.getAgent(agentId);
+        const summary = record?.metadata?._lastSummary;
+        if (!summary) {
+            log(`[mail-inbound] Worker agentId=${agentId} stopped but _lastSummary is empty — ` +
+                `no reply turn posted`);
+            return;
+        }
+        log(`[mail-inbound] Worker agentId=${agentId} stopped — posting reply to ` +
+            `conv=${conversationId}`);
+        const sidecar = getSidecar();
+        if (!sidecar?.postMailTurn) {
+            log(`[mail-inbound] No sidecar/postMailTurn — reply turn dropped`);
+            return;
+        }
+        sidecar.postMailTurn(conversationId, agentId, summary)
+            .then(() => {
+            // Clear the stored summary so it can't replay if the same agentId
+            // is ever reused for another dispatch (the AgentManager generally
+            // mints fresh ids, but this is cheap insurance against a future
+            // change).
+            try {
+                const existingMeta = agentStore.getAgent(agentId)?.metadata ?? {};
+                const { _lastSummary: _drop, ...rest } = existingMeta;
+                void _drop;
+                agentStore.updateAgent(agentId, { metadata: rest });
+            }
+            catch {
+                // best-effort — store may be closing during shutdown
+            }
+        })
+            .catch(() => {
+            // best-effort — hub may be temporarily unreachable
+        });
+    });
+    // ── Cleanup ──────────────────────────────────────────────────
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            try {
+                if (inboxEvents.off) {
+                    inboxEvents.off("inbox.message", onMessage);
+                }
+                else if (inboxEvents.removeListener) {
+                    inboxEvents.removeListener("inbox.message", onMessage);
+                }
+            }
+            catch {
+                // best effort
+            }
+            unsubscribeLifecycle();
+            log(`[mail-inbound] Consumer stopped`);
+        },
+        stats() {
+            pruneSeenTaskIds();
+            return {
+                droppedMalformed: droppedMalformedCount,
+                seenTaskIds: seenTaskIds.size,
+            };
+        },
+    };
+}
+//# sourceMappingURL=mail-inbound-consumer.js.map

package/dist/dispatch/mail-inbound-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-inbound-consumer.js","sourceRoot":"","sources":["../../src/dispatch/mail-inbound-consumer.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/mail-inbound-reuse-consumer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Mail-Inbound Reuse Consumer
+ *
+ * Receives hub-driven `x-dispatch/work` envelopes addressed to **non-sidecar**
+ * agents — long-lived team workers, coordinators, etc. — and drives them
+ * through the dispatch turn using their existing session, then posts the
+ * summary back as a mail turn.
+ *
+ * Mirrors `mail-inbound-consumer.ts` but with three semantic differences:
+ *
+ *   1. Filters envelopes addressed to ANY non-sidecar agent (the existing
+ *      consumer filters for the dispatcher recipient).
+ *   2. Does **not** spawn — it drives the existing agent's session via
+ *      `agentManager.prompt(agentId, prompt)` and watches for `done()` in
+ *      the update stream.
+ *   3. Tracks `inflightDispatches` per agentId. A second envelope arriving
+ *      while the same agent is already processing a dispatch is rejected
+ *      with `recipient_busy` so the orchestrator can retry against another
+ *      agent (or fall back to fresh-spawn). Reject is **dispatch-scoped**
+ *      — non-dispatch work on the agent (peer messages, user chat) does
+ *      NOT trigger the busy reject; that work stacks naturally.
+ *
+ * Reply path: captures `args.summary` from the done() tool call's rawInput
+ * directly off the update stream, so it works for both parented and
+ * parentless target agents (the parented branch in `handlers-v2` does NOT
+ * stash `_lastSummary` — only parentless agents do — but we don't need
+ * that path because we observe done() in-stream).
+ *
+ * @module dispatch/mail-inbound-reuse-consumer
+ */
+import type { AgentManager } from "../agent/agent-manager.js";
+import type { AgentStore } from "../agent/agent-store.js";
+import type { InboxEvents, MailInboundSidecar } from "./mail-inbound-consumer.js";
+export interface MailInboundReuseConsumerOptions {
+    /**
+     * The sidecar agent ID. Envelopes addressed to this id are handled by
+     * the original `mail-inbound-consumer` (fresh-spawn path); the reuse
+     * consumer ignores them so the two consumers' filters don't overlap.
+     */
+    dispatcherAgentId: string;
+    /** Raw inbox event emitter (from inboxAdapter.getInbox().events). */
+    inboxEvents: InboxEvents;
+    /** Agent lifecycle manager — used to drive the existing session. */
+    agentManager: AgentManager;
+    /** Agent store — used to confirm the target agent is running. */
+    agentStore: AgentStore;
+    /**
+     * Optional sidecar reference. Populated after step 13 in boot-v2 via
+     * the shared systemRef. The consumer accesses it lazily at reply time.
+     */
+    getSidecar: () => MailInboundSidecar | null | undefined;
+    /** Optional logger (default: console.log). */
+    log?: (msg: string) => void;
+}
+export interface MailInboundReuseConsumerStats {
+    /** Count of envelopes dropped because they lacked a taskId. */
+    droppedMalformed: number;
+    /** Number of distinct taskIds currently tracked for dedup. */
+    seenTaskIds: number;
+    /** Number of rejects emitted because the target agent was already busy with a dispatch. */
+    busyRejects: number;
+    /** Currently in-flight dispatches keyed by agentId. */
+    inflightCount: number;
+}
+export interface MailInboundReuseConsumer {
+    stop(): void;
+    stats(): MailInboundReuseConsumerStats;
+}
+/**
+ * Wire the mail-inbound reuse consumer.
+ *
+ * Returns a `stop()` handle that detaches the inbox listener.
+ */
+export declare function createMailInboundReuseConsumer(opts: MailInboundReuseConsumerOptions): MailInboundReuseConsumer;
+//# sourceMappingURL=mail-inbound-reuse-consumer.d.ts.map

package/dist/dispatch/mail-inbound-reuse-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-inbound-reuse-consumer.d.ts","sourceRoot":"","sources":["../../src/dispatch/mail-inbound-reuse-consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,KAAK,EACV,WAAW,EAEX,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAUpC,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B,qEAAqE;IACrE,WAAW,EAAE,WAAW,CAAC;IAEzB,oEAAoE;IACpE,YAAY,EAAE,YAAY,CAAC;IAE3B,iEAAiE;IACjE,UAAU,EAAE,UAAU,CAAC;IAEvB;;;OAGG;IACH,UAAU,EAAE,MAAM,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC;IAExD,8CAA8C;IAC9C,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,6BAA6B;IAC5C,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,6BAA6B,CAAC;CACxC;AAUD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,+BAA+B,GACpC,wBAAwB,CAoX1B"}