@mclawnet/swarm 0.1.4 → 0.1.5

package/dist/swarm-coordinator.d.ts

@@ -1,18 +1,61 @@
 import type { SessionAdapter, HubAdapter } from "./types.js";
-import type { MessageRouter } from "./message-router.js";
+import { InboxRelay } from "./inbox-relay.js";
+import { InboxWatcher } from "./inbox-watcher.js";
+import { TaskStore } from "@mclawnet/task";
 import type { SwarmInstance, RoleInstance, SwarmCreateOptions, CustomRoleDefinition } from "./types.js";
 /**
  * SwarmCoordinator — orchestrates multi-role Claude CLI swarms.
  *
  * Composes (not replaces) SessionAdapter. Each role instance is a separate
- * session in SessionAdapter. Communication between roles goes through
- * MessageRouter (currently LocalMessageRouter using stdin/stdout).
+ * session in SessionAdapter. Communication between roles flows through
+ * file-based InboxStore + InboxRelay.
  */
 export declare class SwarmCoordinator {
     private sessionAdapter;
     private hub;
+    /**
+     * Optional factory that resolves a per-swarm TaskStore (workDir-scoped).
+     * When present, spawnRole appends a "### 任务上下文" briefing section to
+     * the role's system prompt. Failures are best-effort logged.
+     *
+     * Backward compat: also accepts a pre-built single TaskStore instance.
+     */
+    private taskStoreFactory?;
+    /**
+     * Optional override for the user-home root (no `.clawnet` suffix).
+     * Threaded to InboxRelay and to inline `new InboxStore(...)` / `TaskStore`
+     * calls so test harnesses pinned to a tmpdir don't fall through to
+     * `homedir()` and write files into the real `~/.clawnet`. When omitted,
+     * inline call sites still honour `CLAWNET_HOME` env var as before.
+     */
+    private home?;
     private swarms;
-    constructor(sessionAdapter: SessionAdapter, hub: HubAdapter);
+    readonly inboxRelay: InboxRelay;
+    readonly inboxWatcher: InboxWatcher;
+    constructor(sessionAdapter: SessionAdapter, hub: HubAdapter, 
+    /**
+     * Optional factory that resolves a per-swarm TaskStore (workDir-scoped).
+     * When present, spawnRole appends a "### 任务上下文" briefing section to
+     * the role's system prompt. Failures are best-effort logged.
+     *
+     * Backward compat: also accepts a pre-built single TaskStore instance.
+     */
+    taskStoreFactory?: (TaskStore | ((workDir: string) => TaskStore | undefined)) | undefined, 
+    /**
+     * Optional override for the user-home root (no `.clawnet` suffix).
+     * Threaded to InboxRelay and to inline `new InboxStore(...)` / `TaskStore`
+     * calls so test harnesses pinned to a tmpdir don't fall through to
+     * `homedir()` and write files into the real `~/.clawnet`. When omitted,
+     * inline call sites still honour `CLAWNET_HOME` env var as before.
+     */
+    home?: string | undefined);
+    /** Resolve the user-home root used for InboxStore / TaskStore lookups. */
+    private resolveHome;
+    /**
+     * Resolve the TaskStore for a given swarm's workDir.
+     * Returns undefined if no factory was wired or if the factory returned undefined.
+     */
+    private resolveTaskStore;
     /** Create a new swarm with two-phase initialization. */
     create(swarmSessionId: string, options: SwarmCreateOptions): Promise<void>;
     /** Handle user message directed at the swarm. */
@@ -37,10 +80,45 @@ export declare class SwarmCoordinator {
             total: number;
         };
     }): boolean;
+    /**
+     * Persist the per-role claudeSessionId immediately (e.g. from `system/init`
+     * frame, before the first turn_complete). Returns true if a role was found
+     * and updated; false otherwise (no-op for non-swarm sessions).
+     */
+    setRoleClaudeSessionId(swarmId: string, instanceId: string, claudeSessionId: string): boolean;
+    /** Convenience: same as setRoleClaudeSessionId but takes the `${swarmId}::${instanceId}` roleSessionId. */
+    setRoleClaudeSessionIdBySession(roleSessionId: string, claudeSessionId: string): boolean;
     /** Spawn a new role instance in a swarm. */
-    spawnRole(swarmId: string, roleName: string, router?: MessageRouter, taskPrompt?: string, customPrompt?: string, customDefinition?: CustomRoleDefinition, additionalDirs?: string[]): Promise<RoleInstance>;
+    spawnRole(swarmId: string, roleName: string, taskPrompt?: string, customPrompt?: string, customDefinition?: CustomRoleDefinition, additionalDirs?: string[], resumeId?: string, presetInstanceId?: string): Promise<RoleInstance>;
+    /**
+     * Recover a previously persisted swarm by id.
+     *
+     * Locates the snapshot via `listRecoverableSwarmIds()`, then for each role
+     * in the snapshot spawns a Claude session via `--resume role.claudeSessionId`
+     * (when present) so the per-role conversation continues. Roles without a
+     * stored claudeSessionId start fresh.
+     *
+     * After all roles are spawned, drains each role's offline inbox via
+     * `inboxRelay.deliver`. Drain failures are best-effort: warn but never throw.
+     *
+     * Recovered swarms start in `paused` state — caller must explicitly resume
+     * (matches existing behaviour in `recoverSwarm` helper).
+     */
+    recover(swarmId: string): Promise<void>;
     /** Stop a role instance. */
     stopRole(swarmId: string, instanceId: string): Promise<void>;
+    /**
+     * Roll back side-effects from a partially-completed `create()`.
+     *
+     * Called from create()'s catch block. Mirrors `destroy()` but is
+     * deliberately tolerant of partial state (timer may not exist, snapshot
+     * may not exist, sessions list comes from the caller's accumulator
+     * because `swarm.roles` may not yet contain every opened session).
+     *
+     * Best-effort: every step is wrapped — we never throw out of cleanup.
+     * Logs a warn so operators see WHY a swarm was rolled back.
+     */
+    private cleanupPartialCreate;
     /** Destroy an entire swarm. */
     destroy(swarmId: string): Promise<void>;
     /** Check if a session ID belongs to any swarm. */
@@ -53,22 +131,108 @@ export declare class SwarmCoordinator {
     complete(swarmId: string): Promise<void>;
     /** Mark a swarm as failed. Releases all resources — closes sessions, deletes snapshot, removes from memory. */
     fail(swarmId: string): Promise<void>;
+    /**
+     * InboxRelay messageInterceptor hook. Consumes `plan_review_result`
+     * envelopes (written by the `plan_review_submit` MCP tool out-of-process)
+     * and converts them into the normalized `submitPlanReview()` flow:
+     * planStatus flip, timer clear, plan_approved/plan_rejected to queen.
+     *
+     * Returning `true` removes the raw message from the LLM payload and marks
+     * it delivered so it doesn't re-fire. Returning `false` lets the relay
+     * push the message normally.
+     *
+     * Failures (parse error, invalid verdict) are logged + consumed to avoid a
+     * tight reload loop on a malformed file. The submitPlanReview call is
+     * idempotent so duplicate reviewer envelopes (e.g. retries) are safe.
+     */
+    private handleInterceptedMessage;
+    /**
+     * Apply a plan review verdict from a reviewer (or system on timeout).
+     * Idempotent: when planStatus is already "approved" or "rejected", logs and
+     * returns. Clears any pending planReviewTimer.
+     *
+     * Wired to the `plan_review_submit` MCP tool by the host (Task 3); this
+     * method itself does not call back into MCP.
+     */
+    submitPlanReview(args: {
+        swarmId: string;
+        from: string;
+        verdict: "approved" | "rejected";
+        body?: string;
+    }): Promise<void>;
+    /**
+     * Defensive recovery: re-emit plan_approved / plan_rejected to the queen if
+     * planStatus is finalised but no matching system envelope exists in the
+     * queen's inbox. Called from the queen check-in tick.
+     *
+     * Catches the case where the deferred submitPlanReview's call to
+     * deliverInbox() threw (e.g. transient fs error or lockfile contention) and
+     * only logged a warning — leaving planStatus = "approved" but the queen
+     * never receiving plan_approved, which would otherwise wedge the swarm.
+     *
+     * Idempotent: if a system plan_approved/plan_rejected already exists in the
+     * queen inbox (delivered or undelivered), we do nothing.
+     */
+    private reconcilePlanStatusForQueen;
     /** Run retrospective analysis then clean up swarm resources. */
     private runRetroAndCleanup;
+    /**
+     * Detach all tasks owned by a swarm: clear their swarmId and owner so they
+     * survive the swarm's lifecycle and can be reassigned. Best-effort — any
+     * failure is logged and swallowed; never blocks destroy/complete/fail.
+     *
+     * Tasks belonging to other swarms are not touched.
+     */
+    private detachTasks;
+    /**
+     * Build the boot-time "### 任务上下文" section appended to a role's system
+     * prompt. Returns null when no taskStore is wired (caller already gates on
+     * that, but we double-check here for safety).
+     *
+     * Queen vs. worker contract:
+     *   - queen → lead briefing (queenInstanceId is this role itself) + member briefing
+     *   - other → task briefing (owner-scoped) + member briefing
+     *
+     * The "### 任务上下文" anchor and inner section anchors are load-bearing
+     * (matched verbatim by tests and by the agent itself).
+     */
+    private buildBriefingSection;
+    /**
+     * Append a message to a target instance's inbox file then trigger
+     * InboxRelay.deliver to push it through the agent's stdin (single-flight).
+     * Best-effort: returns silently when the swarm has no workDir (in-memory
+     * fixtures used by tests), keeping behaviour compatible with the previous
+     * router.send path.
+     */
+    private deliverInbox;
+    /**
+     * Broadcast helper: deliverInbox to every role in the swarm except those
+     * already stopped. Includes `spawning` roles intentionally — the inbox file
+     * is durable, so the relay (or runPostStart drain in the spawn path) will
+     * deliver the message once the role's stdin opens. Matches the legacy
+     * router.broadcast behaviour, which never gated on "spawning".
+     */
+    private broadcastInbox;
     private findQueen;
+    /**
+     * Public lookup: returns the active queen role instance for a swarm, or
+     * undefined when the swarm/queen is not present. Identifies the queen by
+     * `definition.type === "queen"` (not by roleName) so custom queen roles
+     * with non-default names are also recognised.
+     */
+    findQueenInstance(swarmId: string): RoleInstance | undefined;
     private findReviewer;
     /** Build a summary of the previous swarm run from messages.jsonl for continuation. */
     private buildContinuationSummary;
     /** Send plan to reviewer for review. Auto-approves if no reviewer available. */
     private requestPlanReview;
-    /** Handle plan review result from reviewer. */
-    private handlePlanReviewResult;
+    /**
+     * (Re)arm the plan-review timeout fallback. Clears any prior timer first so
+     * call sites don't need to. The fire path delegates to submitPlanReview so
+     * its idempotency guard protects against reviewer/timer races.
+     */
+    private armPlanReviewTimeout;
     private findByRoleSessionId;
-    private executeAction;
-    /** On-demand spawn: start a role instance if it's not currently running. */
-    private ensureRoleStarted;
-    /** Send a message with exponential backoff retry. Fire-and-forget (async). */
-    private sendWithRetry;
     private startQueenCheck;
     private buildRoleListString;
     private buildStatusPayload;

package/dist/swarm-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-coordinator.d.ts","sourceRoot":"","sources":["../src/swarm-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EAGlB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAWpB;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,GAAG;IAJb,OAAO,CAAC,MAAM,CAAoC;gBAGxC,cAAc,EAAE,cAAc,EAC9B,GAAG,EAAE,UAAU;IAKzB,wDAAwD;IAClD,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0GhF,iDAAiD;IAC3C,iBAAiB,CACrB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAwChB;;;;;OAKG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO;IA+D/D;;;OAGG;IACH,sBAAsB,CACpB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACnH,OAAO;IAoBV,4CAA4C;IACtC,SAAS,CACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,aAAa,EACtB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,EACrB,gBAAgB,CAAC,EAAE,oBAAoB,EACvC,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC,YAAY,CAAC;IAwExB,4BAA4B;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE,+BAA+B;IACzB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7C,kDAAkD;IAClD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI1C,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAIzC,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI3D,kHAAkH;IAC5G,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9C,+GAA+G;IACzG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1C,gEAAgE;YAClD,kBAAkB;IAsEhC,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,YAAY;IAOpB,sFAAsF;IACtF,OAAO,CAAC,wBAAwB;IAkChC,gFAAgF;IAChF,OAAO,CAAC,iBAAiB;IA2CzB,+CAA+C;IAC/C,OAAO,CAAC,sBAAsB;IAyC9B,OAAO,CAAC,mBAAmB;YAeb,aAAa;IAiI3B,4EAA4E;YAC9D,iBAAiB;IAwC/B,8EAA8E;YAChE,aAAa;IAqD3B,OAAO,CAAC,eAAe;IA8DvB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,gBAAgB;CAWzB"}
+{"version":3,"file":"swarm-coordinator.d.ts","sourceRoot":"","sources":["../src/swarm-coordinator.ts"],"names":[],"mappings":"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"}