@desplega.ai/agent-swarm 1.71.2 → 1.72.0

package/src/providers/swarm-events-shared.ts

@@ -0,0 +1,262 @@
+/**
+ * Shared adapter-side swarm-event handler factory.
+ *
+ * Phase 5 extraction (see thoughts/.../2026-04-28-claude-managed-agents-provider.md
+ * § Phase 5). Originally lived inline in `codex-swarm-events.ts`; lifted out
+ * here so the `claude-managed` adapter (and any future adapter that wants the
+ * same throttle/poll/heartbeat scaffolding) can reuse it.
+ *
+ * ## What this owns
+ *
+ * - `apiHeaders`, `fireAndForget`
+ * - Throttle constants and the `shouldRun` gate
+ * - `checkCancelled`, `checkLoop`, `heartbeat`, `activity`
+ * - `progressContextUsage`, `progressCompaction`, `progressCompletion`
+ *
+ * ## What this does NOT own
+ *
+ * Provider-specific dispatch lives in each adapter's `*-swarm-events.ts`. For
+ * example codex's per-turn cost-data shape, or claude-managed's interrupt+
+ * archive cancel callback. The shared file exposes the throttled primitives
+ * and a generic event-dispatch shell; the per-provider wrapper supplies any
+ * `onCancel` / extension points it needs.
+ *
+ * ## Two-layer cancellation (unchanged from codex)
+ *
+ * Layer 1 — runner-side polling: `src/commands/runner.ts` polls
+ * `GET /cancelled-tasks` on a timer and calls `session.abort()`. All providers
+ * inherit this for free.
+ *
+ * Layer 2 — adapter-side (this file): on every `tool_start` we (throttled)
+ * check the same endpoint and abort the running turn via the shared
+ * `AbortController`. This *accelerates* cancellation latency.
+ *
+ * ## Hard contract
+ *
+ * - The handler is synchronous from the caller's perspective.
+ * - Every fetch is fire-and-forget with `.catch(() => {})` so a single bad
+ *   request never breaks the session.
+ * - The handler never throws — `try/catch` around the dispatch swallows
+ *   everything for safety.
+ */
+
+import { checkToolLoop } from "../hooks/tool-loop-detection";
+import type { ProviderEvent } from "./types";
+
+/** Throttle windows (ms) keyed by action name. Exported for unit assertions. */
+export const CANCELLATION_THROTTLE_MS = 500;
+export const HEARTBEAT_THROTTLE_MS = 5_000;
+export const ACTIVITY_THROTTLE_MS = 5_000;
+export const CONTEXT_THROTTLE_MS = 30_000;
+
+export interface SwarmEventHandlerOpts {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  /** Task currently being worked on. When null, all task-scoped hooks are no-ops. */
+  taskId: string | null;
+  /** Mutable reference to the session's per-turn AbortController. */
+  abortRef: { current: AbortController | null };
+  /**
+   * Optional callback invoked when a cancellation is detected (in addition to
+   * the abort-controller fire). Adapters that need provider-specific cancel
+   * actions (e.g. claude-managed sending `user.interrupt` + archiving) wire
+   * it here. Errors are swallowed.
+   */
+  onCancel?: () => void | Promise<void>;
+  /**
+   * Prefix used in the synthetic `sessionId` body field on context POSTs when
+   * `session_init` hasn't fired yet. Codex preserves its historical
+   * `codex-${taskId}` shape; new providers can pick their own.
+   */
+  sessionIdFallbackPrefix?: string;
+}
+
+export function apiHeaders(opts: SwarmEventHandlerOpts): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${opts.apiKey}`,
+    "X-Agent-ID": opts.agentId,
+  };
+}
+
+export function fireAndForget(url: string, init: RequestInit): void {
+  void fetch(url, init).catch(() => {});
+}
+
+/**
+ * Build the handler. The returned function reacts to normalized events.
+ *
+ * Mirrors the codex-swarm-events behavior exactly — providers that want
+ * additional event-type handling can compose this with their own dispatch
+ * (e.g. by wrapping the returned handler).
+ */
+export function createSwarmEventHandler(
+  opts: SwarmEventHandlerOpts,
+): (event: ProviderEvent) => void {
+  const lastCall: Record<string, number> = {};
+  let sessionId: string | undefined;
+
+  const shouldRun = (key: string, throttleMs: number): boolean => {
+    const now = Date.now();
+    if (now - (lastCall[key] ?? 0) < throttleMs) return false;
+    lastCall[key] = now;
+    return true;
+  };
+
+  const checkCancelled = (): void => {
+    const taskId = opts.taskId;
+    if (!taskId) return;
+    void (async () => {
+      try {
+        const res = await fetch(
+          `${opts.apiUrl}/cancelled-tasks?taskId=${encodeURIComponent(taskId)}`,
+          { headers: apiHeaders(opts) },
+        );
+        if (!res.ok) return;
+        const data = (await res.json()) as {
+          cancelled?: Array<{ id: string; failureReason?: string }>;
+        };
+        const isCancelled = data.cancelled?.some((t) => t.id === taskId);
+        if (isCancelled) {
+          opts.abortRef.current?.abort();
+          if (opts.onCancel) {
+            try {
+              await opts.onCancel();
+            } catch {
+              // Swallow — best-effort.
+            }
+          }
+        }
+      } catch {
+        // Swallow — fire-and-forget.
+      }
+    })();
+  };
+
+  const checkLoop = (toolName: string, args: unknown): void => {
+    const taskId = opts.taskId;
+    if (!taskId) return;
+    const argRecord = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+    void checkToolLoop(taskId, toolName, argRecord)
+      .then((result) => {
+        if (result.blocked) {
+          opts.abortRef.current?.abort();
+        }
+      })
+      .catch(() => {});
+  };
+
+  const heartbeat = (): void => {
+    if (opts.taskId && shouldRun("heartbeat", HEARTBEAT_THROTTLE_MS)) {
+      fireAndForget(
+        `${opts.apiUrl}/api/active-sessions/heartbeat/${encodeURIComponent(opts.taskId)}`,
+        { method: "PUT", headers: apiHeaders(opts) },
+      );
+    }
+  };
+
+  const activity = (): void => {
+    if (shouldRun("activity", ACTIVITY_THROTTLE_MS)) {
+      fireAndForget(`${opts.apiUrl}/api/agents/${encodeURIComponent(opts.agentId)}/activity`, {
+        method: "PUT",
+        headers: apiHeaders(opts),
+      });
+    }
+  };
+
+  const progressContextUsage = (event: {
+    contextUsedTokens: number;
+    contextTotalTokens: number;
+    contextPercent: number;
+  }): void => {
+    if (opts.taskId && shouldRun("context-progress", CONTEXT_THROTTLE_MS)) {
+      fireAndForget(`${opts.apiUrl}/api/tasks/${encodeURIComponent(opts.taskId)}/context`, {
+        method: "POST",
+        headers: apiHeaders(opts),
+        body: JSON.stringify({
+          eventType: "progress",
+          sessionId: sessionId ?? `${opts.sessionIdFallbackPrefix ?? "session"}-${opts.taskId}`,
+          contextUsedTokens: event.contextUsedTokens,
+          contextTotalTokens: event.contextTotalTokens,
+          contextPercent: event.contextPercent,
+        }),
+      });
+    }
+  };
+
+  const progressCompaction = (event: {
+    contextTotalTokens: number;
+    preCompactTokens?: number;
+    compactTrigger?: string;
+  }): void => {
+    if (opts.taskId) {
+      fireAndForget(`${opts.apiUrl}/api/tasks/${encodeURIComponent(opts.taskId)}/context`, {
+        method: "POST",
+        headers: apiHeaders(opts),
+        body: JSON.stringify({
+          eventType: "compaction",
+          sessionId: sessionId ?? `${opts.sessionIdFallbackPrefix ?? "session"}-${opts.taskId}`,
+          contextTotalTokens: event.contextTotalTokens,
+          preCompactTokens: event.preCompactTokens,
+          compactTrigger: event.compactTrigger,
+        }),
+      });
+    }
+  };
+
+  const progressCompletion = (): void => {
+    if (opts.taskId) {
+      fireAndForget(`${opts.apiUrl}/api/tasks/${encodeURIComponent(opts.taskId)}/context`, {
+        method: "POST",
+        headers: apiHeaders(opts),
+        body: JSON.stringify({
+          eventType: "completion",
+          sessionId: sessionId ?? `${opts.sessionIdFallbackPrefix ?? "session"}-${opts.taskId}`,
+        }),
+      });
+    }
+  };
+
+  return (event: ProviderEvent): void => {
+    try {
+      switch (event.type) {
+        case "session_init": {
+          sessionId = event.sessionId;
+          break;
+        }
+        case "tool_start": {
+          if (shouldRun("cancellation", CANCELLATION_THROTTLE_MS)) {
+            checkCancelled();
+          }
+          checkLoop(event.toolName, event.args);
+          heartbeat();
+          activity();
+          break;
+        }
+        case "context_usage": {
+          progressContextUsage({
+            contextUsedTokens: event.contextUsedTokens,
+            contextTotalTokens: event.contextTotalTokens,
+            contextPercent: event.contextPercent,
+          });
+          break;
+        }
+        case "compaction": {
+          progressCompaction({
+            contextTotalTokens: event.contextTotalTokens,
+            preCompactTokens: event.preCompactTokens,
+            compactTrigger: event.compactTrigger,
+          });
+          break;
+        }
+        case "result": {
+          progressCompletion();
+          break;
+        }
+      }
+    } catch {
+      // Never throw from the handler — the event loop is hot.
+    }
+  };
+}

package/src/providers/types.ts

@@ -12,11 +12,25 @@ export interface CostData {
   numTurns: number;
   model: string;
   isError: boolean;
+  /**
+   * Phase 6: tells the API which recompute path to use on
+   * `POST /api/session-costs`. Codex triggers the pricing-table recompute
+   * (when DB pricing rows exist for all three token classes); Claude / pi
+   * always trust the harness-reported `totalCostUsd` as-is.
+   */
+  provider?: "claude" | "codex" | "pi";
 }
 
+import type { ProviderName } from "../types";
+
 /** Normalized event emitted by any provider adapter. */
 export type ProviderEvent =
-  | { type: "session_init"; sessionId: string }
+  | {
+      type: "session_init";
+      sessionId: string;
+      provider?: ProviderName;
+      providerMeta?: Record<string, unknown>;
+    }
   | { type: "message"; role: "assistant" | "user"; content: string }
   | { type: "tool_start"; toolCallId: string; toolName: string; args: unknown }
   | { type: "tool_end"; toolCallId: string; toolName: string; result: unknown }
@@ -24,6 +38,7 @@ export type ProviderEvent =
   | { type: "error"; message: string; category?: string }
   | { type: "raw_log"; content: string }
   | { type: "raw_stderr"; content: string }
+  | { type: "progress"; message: string }
   | { type: "custom"; name: string; data: unknown }
   | {
       type: "context_usage";
@@ -50,6 +65,7 @@ export interface ProviderSessionConfig {
   apiUrl: string;
   apiKey: string;
   cwd: string;
+  vcsRepo?: string;
   resumeSessionId?: string;
   iteration?: number;
   logFile: string;
@@ -79,9 +95,18 @@ export interface ProviderResult {
   failureReason?: string;
 }
 
+/** Behavioral traits that govern prompt assembly and feature gating. */
+export interface ProviderTraits {
+  /** Provider can call MCP tools (store-progress, task-action, skills, slack-reply, etc.) */
+  hasMcp: boolean;
+  /** Provider runs in the local Docker container with /workspace, identity files, agent-fs, PM2, etc. */
+  hasLocalEnvironment: boolean;
+}
+
 /** Main contract for a harness provider adapter. */
 export interface ProviderAdapter {
   readonly name: string;
+  readonly traits: ProviderTraits;
   createSession(config: ProviderSessionConfig): Promise<ProviderSession>;
   canResume(sessionId: string): Promise<boolean>;
   formatCommand(commandName: string): string;

package/src/tests/base-prompt.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { type BasePromptArgs, getBasePrompt } from "../prompts/base-prompt";
+import type { ProviderTraits } from "../providers/types";
 
 /** Minimal valid args to reduce boilerplate */
 const minimalArgs: BasePromptArgs = {
@@ -334,3 +335,201 @@ describe("getBasePrompt — truncation", () => {
     expect(result).not.toContain("[...truncated");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Remote provider (no MCP, no local environment) — trait-aware prompt assembly
+// ---------------------------------------------------------------------------
+const remoteTraits: ProviderTraits = { hasMcp: false, hasLocalEnvironment: false };
+const remoteProviderArgs: BasePromptArgs = {
+  ...minimalArgs,
+  traits: remoteTraits,
+};
+
+describe("getBasePrompt — remote provider composite selection", () => {
+  test("uses remote worker composite (not generic worker)", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    // Remote worker template says "output is captured automatically"
+    expect(result).toContain("output is captured automatically");
+    // Should NOT contain generic worker tools
+    expect(result).not.toContain("store-progress");
+    expect(result).not.toContain("task-action");
+    expect(result).not.toContain("read-messages");
+  });
+
+  test("still includes role and agentId", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).toContain("worker");
+    expect(result).toContain("agent-abc-123");
+  });
+});
+
+describe("getBasePrompt — remote provider excluded sections", () => {
+  test("excludes join-swarm / register instructions", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("join-swarm");
+  });
+
+  test("excludes /workspace filesystem layout", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("/workspace/personal");
+    expect(result).not.toContain("/workspace/shared");
+  });
+
+  test("excludes How You Are Built section", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("How You Are Built");
+    expect(result).not.toContain("hooks fire during your session");
+  });
+
+  test("excludes context mode tools", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("context-mode");
+    expect(result).not.toContain("batch_execute");
+  });
+
+  test("excludes system packages section", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("sudo apt-get install");
+    expect(result).not.toContain("System packages available");
+  });
+
+  test("excludes VCS CLI tools table", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("glab mr create");
+    expect(result).not.toContain("gh pr create");
+  });
+
+  test("excludes service registry / PM2", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("Service Registry");
+    expect(result).not.toContain("pm2 start");
+  });
+
+  test("excludes code quality section", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).not.toContain("Code Quality");
+    expect(result).not.toContain("--no-verify");
+  });
+
+  test("excludes capabilities listing", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      capabilities: ["core", "task-pool"],
+    });
+    expect(result).not.toContain("Capabilities enabled");
+  });
+
+  test("skips Slack instructions even with slackContext", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      slackContext: { channelId: "C123", threadTs: "123.456" },
+    });
+    expect(result).not.toContain("slack-reply");
+    expect(result).not.toContain("C123");
+  });
+
+  test("skips skills section even when provided", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      skillsSummary: [{ name: "commit", description: "Create a commit" }],
+    });
+    expect(result).not.toContain("Installed Skills");
+    expect(result).not.toContain("/commit");
+  });
+
+  test("skips MCP servers section even when provided", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      mcpServersSummary: "- my-server: http://localhost:3000",
+    });
+    expect(result).not.toContain("Installed MCP Servers");
+    expect(result).not.toContain("my-server");
+  });
+
+  test("skips CLAUDE.md and TOOLS.md truncatable sections", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      claudeMd: "# Agent instructions here",
+      toolsMd: "# Tools here",
+    });
+    expect(result).not.toContain("Agent Instructions");
+    expect(result).not.toContain("Agent instructions here");
+    expect(result).not.toContain("Your Tools & Capabilities");
+    expect(result).not.toContain("Tools here");
+  });
+});
+
+describe("getBasePrompt — remote provider identity", () => {
+  test("uses simplified identity (no SOUL.md / IDENTITY.md)", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      name: "remote-worker-1",
+      description: "A remote worker",
+      soulMd: "# SOUL.md content that should NOT appear",
+      identityMd: "# IDENTITY.md content that should NOT appear",
+    });
+    expect(result).toContain("**Name:** remote-worker-1");
+    expect(result).toContain("**Description:** A remote worker");
+    expect(result).toContain("Desplega platform");
+    // Identity files should NOT be injected
+    expect(result).not.toContain("SOUL.md content that should NOT appear");
+    expect(result).not.toContain("IDENTITY.md content that should NOT appear");
+  });
+
+  test("identity section present even without name", async () => {
+    const result = await getBasePrompt(remoteProviderArgs);
+    expect(result).toContain("Your Identity");
+    expect(result).toContain("Desplega platform");
+  });
+});
+
+describe("getBasePrompt — remote provider keeps repo context", () => {
+  test("skips CLAUDE.md content for remote providers", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      repoContext: {
+        claudeMd: "Run `bun test` before pushing.",
+        clonePath: "/workspace/repos/my-repo",
+      },
+    });
+    expect(result).toContain("Repository Context");
+    // Remote providers don't get claudeMd injected
+    expect(result).not.toContain("Run `bun test` before pushing.");
+    expect(result).not.toContain("/workspace/repos/my-repo");
+  });
+
+  test("includes repo guidelines", async () => {
+    const result = await getBasePrompt({
+      ...remoteProviderArgs,
+      repoContext: {
+        clonePath: "/workspace/repos/my-repo",
+        guidelines: {
+          prChecks: ["bun run lint:fix", "bun test"],
+          mergeChecks: [],
+          allowMerge: false,
+          review: [],
+        },
+      },
+    });
+    expect(result).toContain("Repository Guidelines");
+    expect(result).toContain("bun run lint:fix");
+    expect(result).toContain("bun test");
+  });
+});
+
+describe("getBasePrompt — local providers unaffected", () => {
+  test("local provider uses generic worker composite", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      traits: { hasMcp: true, hasLocalEnvironment: true },
+    });
+    expect(result).toContain("store-progress");
+    expect(result).toContain("/workspace");
+  });
+
+  test("undefined traits defaults to local provider behavior", async () => {
+    const result = await getBasePrompt(minimalArgs);
+    expect(result).toContain("store-progress");
+    expect(result).toContain("/workspace");
+  });
+});