@desplega.ai/agent-swarm 1.71.2 → 1.72.0

package/src/providers/devin-api.ts

@@ -0,0 +1,207 @@
+/**
+ * Thin REST client for Devin v3 API endpoints.
+ *
+ * All functions authenticate via Bearer token and target the organization-scoped
+ * v3 routes. The base URL defaults to `https://api.devin.ai` but can be
+ * overridden via `DEVIN_API_BASE_URL` for testing or on-prem deployments.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DevinSessionStatus =
+  | "new"
+  | "creating"
+  | "claimed"
+  | "running"
+  | "exit"
+  | "error"
+  | "suspended"
+  | "resuming";
+
+export type DevinStatusDetail =
+  | "working"
+  | "waiting_for_user"
+  | "waiting_for_approval"
+  | "finished"
+  | "inactivity"
+  | "user_request"
+  | "usage_limit_exceeded"
+  | "out_of_credits"
+  | "out_of_quota"
+  | "no_quota_allocation"
+  | "payment_declined"
+  | "org_usage_limit_exceeded"
+  | "error";
+
+export interface DevinSessionCreateRequest {
+  prompt: string;
+  playbook_id?: string;
+  repos?: string[];
+  structured_output_schema?: object;
+  tags?: string[];
+  title?: string;
+  max_acu_limit?: number;
+  bypass_approval?: boolean;
+  session_secrets?: Array<{ key: string; value: string; sensitive?: boolean }>;
+}
+
+export interface DevinSessionResponse {
+  session_id: string;
+  url: string;
+  status: DevinSessionStatus;
+  status_detail?: DevinStatusDetail;
+  structured_output?: unknown;
+  pull_requests?: Array<{ pr_url: string; pr_state: string }>;
+  acus_consumed?: number;
+  title?: string;
+  tags?: string[];
+  created_at: number;
+  updated_at: number;
+}
+
+export interface DevinSessionMessage {
+  event_id: string;
+  source: "devin" | "user";
+  message: string;
+  created_at: number;
+}
+
+export interface DevinMessagesResponse {
+  items: DevinSessionMessage[];
+  end_cursor: string | null;
+  has_next_page: boolean;
+  total: number | null;
+}
+
+export interface DevinPlaybookCreateRequest {
+  title: string;
+  body: string;
+}
+
+export interface DevinPlaybookResponse {
+  playbook_id: string;
+  title: string;
+  body: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function baseUrl(): string {
+  return process.env.DEVIN_API_BASE_URL ?? "https://api.devin.ai";
+}
+
+function headers(apiKey: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+  };
+}
+
+async function assertOk(res: Response, label: string): Promise<void> {
+  if (!res.ok) {
+    let body = "";
+    try {
+      body = await res.text();
+    } catch {
+      // Ignore read errors.
+    }
+    throw new Error(`[devin-api] ${label} failed: HTTP ${res.status} — ${body}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API functions
+// ---------------------------------------------------------------------------
+
+/** Create a new Devin session. */
+export async function createSession(
+  orgId: string,
+  apiKey: string,
+  request: DevinSessionCreateRequest,
+): Promise<DevinSessionResponse> {
+  const res = await fetch(`${baseUrl()}/v3/organizations/${orgId}/sessions`, {
+    method: "POST",
+    headers: headers(apiKey),
+    body: JSON.stringify(request),
+  });
+  await assertOk(res, "createSession");
+  return (await res.json()) as DevinSessionResponse;
+}
+
+/** Get the current state of a Devin session. */
+export async function getSession(
+  orgId: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<DevinSessionResponse> {
+  const res = await fetch(`${baseUrl()}/v3/organizations/${orgId}/sessions/${sessionId}`, {
+    method: "GET",
+    headers: headers(apiKey),
+  });
+  await assertOk(res, "getSession");
+  return (await res.json()) as DevinSessionResponse;
+}
+
+/** Send a message to a running Devin session. */
+export async function sendMessage(
+  orgId: string,
+  apiKey: string,
+  sessionId: string,
+  message: string,
+): Promise<void> {
+  const res = await fetch(`${baseUrl()}/v3/organizations/${orgId}/sessions/${sessionId}/messages`, {
+    method: "POST",
+    headers: headers(apiKey),
+    body: JSON.stringify({ message }),
+  });
+  await assertOk(res, "sendMessage");
+}
+
+/** Archive (terminate) a Devin session. */
+export async function archiveSession(
+  orgId: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<void> {
+  const res = await fetch(`${baseUrl()}/v3/organizations/${orgId}/sessions/${sessionId}/archive`, {
+    method: "POST",
+    headers: headers(apiKey),
+  });
+  await assertOk(res, "archiveSession");
+}
+
+/** Fetch session messages (cursor-based pagination). */
+export async function getSessionMessages(
+  orgId: string,
+  apiKey: string,
+  sessionId: string,
+  after?: string,
+): Promise<DevinMessagesResponse> {
+  const params = new URLSearchParams({ first: "200" });
+  if (after) params.set("after", after);
+  const res = await fetch(
+    `${baseUrl()}/v3/organizations/${orgId}/sessions/${sessionId}/messages?${params}`,
+    { method: "GET", headers: headers(apiKey) },
+  );
+  await assertOk(res, "getSessionMessages");
+  return (await res.json()) as DevinMessagesResponse;
+}
+
+/** Create a new playbook. */
+export async function createPlaybook(
+  orgId: string,
+  apiKey: string,
+  request: DevinPlaybookCreateRequest,
+): Promise<DevinPlaybookResponse> {
+  const res = await fetch(`${baseUrl()}/v3/organizations/${orgId}/playbooks`, {
+    method: "POST",
+    headers: headers(apiKey),
+    body: JSON.stringify(request),
+  });
+  await assertOk(res, "createPlaybook");
+  return (await res.json()) as DevinPlaybookResponse;
+}

package/src/providers/devin-playbooks.ts

@@ -0,0 +1,91 @@
+/**
+ * Playbook cache helper for Devin provider.
+ *
+ * Maintains a SHA-256 hash → playbook_id cache backed by swarm_config so
+ * playbook IDs survive process restarts. An in-memory Map sits in front
+ * to avoid repeated HTTP round-trips within the same process.
+ */
+
+import { createPlaybook } from "./devin-api";
+
+const CONFIG_KEY_PREFIX = "devin_playbook_";
+
+/** In-memory cache: SHA-256 hash of body -> playbook_id */
+const playbookCache = new Map<string, string>();
+
+async function loadFromConfig(
+  swarmApiUrl: string,
+  swarmApiKey: string,
+  hash: string,
+): Promise<string | null> {
+  try {
+    const key = `${CONFIG_KEY_PREFIX}${hash}`;
+    const res = await fetch(`${swarmApiUrl}/api/config/resolved?key=${key}`, {
+      headers: { Authorization: `Bearer ${swarmApiKey}` },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { configs: Array<{ key: string; value: string }> };
+    const entry = data.configs?.find((c) => c.key === key);
+    return entry?.value ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function saveToConfig(
+  swarmApiUrl: string,
+  swarmApiKey: string,
+  hash: string,
+  playbookId: string,
+): Promise<void> {
+  await fetch(`${swarmApiUrl}/api/config`, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${swarmApiKey}`,
+    },
+    body: JSON.stringify({
+      scope: "global",
+      key: `${CONFIG_KEY_PREFIX}${hash}`,
+      value: playbookId,
+      description: `Devin playbook cache (hash: ${hash.slice(0, 12)}...)`,
+    }),
+  });
+}
+
+/**
+ * Return the playbook_id for the given body, creating the playbook via the
+ * Devin API if it has not been seen before.
+ */
+export async function getOrCreatePlaybook(
+  orgId: string,
+  apiKey: string,
+  title: string,
+  body: string,
+  swarmApiUrl?: string,
+  swarmApiKey?: string,
+): Promise<string> {
+  const hash = new Bun.CryptoHasher("sha256").update(body).digest("hex");
+
+  const cached = playbookCache.get(hash);
+  if (cached) return cached;
+
+  if (swarmApiUrl && swarmApiKey) {
+    const persisted = await loadFromConfig(swarmApiUrl, swarmApiKey, hash);
+    if (persisted) {
+      playbookCache.set(hash, persisted);
+      return persisted;
+    }
+  }
+
+  const response = await createPlaybook(orgId, apiKey, { title, body });
+  playbookCache.set(hash, response.playbook_id);
+
+  if (swarmApiUrl && swarmApiKey) {
+    saveToConfig(swarmApiUrl, swarmApiKey, hash, response.playbook_id).catch((err) =>
+      console.warn(`[devin] playbook cache save failed: ${err}`),
+    );
+  }
+
+  return response.playbook_id;
+}

package/src/providers/devin-skill-resolver.ts

@@ -0,0 +1,113 @@
+/**
+ * Devin skill resolver.
+ *
+ * Devin has no native skill system, so we inline SKILL.md content into the
+ * prompt before sending it to the Devin API.
+ *
+ * If the very first line of the prompt matches `@skills:<name> <args>`, we
+ * look up `${skillsDir}/<name>/SKILL.md` and (if found) inline its contents
+ * at the top of the new prompt, with the rest of the original prompt
+ * preserved as "User request: ...".
+ *
+ * This mirrors the pattern in codex-skill-resolver.ts.
+ */
+
+import { join } from "node:path";
+import type { ProviderEvent } from "./types";
+
+/**
+ * Regex matching a leading `@skills:<name>` on a single line.
+ *
+ * - Must start with `@skills:`
+ * - Skill name is `[a-z0-9:_-]+`
+ * - Optional trailing args captured greedily in group 2
+ */
+const SKILL_COMMAND_REGEX = /^@skills:([a-z0-9:_-]+)(?:\s+(.*))?$/;
+
+const MAX_SKILL_CHARS = Number(process.env.MAX_SKILL_CHARS) || 100_000;
+
+/**
+ * Default skills directory — `plugin/pi-skills/` relative to the project root.
+ *
+ * Precedence:
+ * 1. `DEVIN_SKILLS_DIR` env var (useful for tests / custom installs)
+ * 2. `<project-root>/plugin/pi-skills`
+ */
+function defaultSkillsDir(): string {
+  if (process.env.DEVIN_SKILLS_DIR) {
+    return process.env.DEVIN_SKILLS_DIR;
+  }
+  // import.meta.dir is src/providers/ — go up two levels to project root
+  return join(import.meta.dir, "..", "..", "plugin", "pi-skills");
+}
+
+/**
+ * Inline a skill into the prompt if the first line matches `@skills:<name>`.
+ *
+ * @param prompt - Raw prompt from the runner
+ * @param skillsDir - Absolute path to the skills directory. Defaults to
+ *   `plugin/pi-skills/` in the project root.
+ * @param emit - Optional callback to surface warnings via `raw_stderr` events.
+ * @returns The rewritten prompt, or the original if there's nothing to inline.
+ */
+export async function resolveDevinPrompt(
+  prompt: string,
+  skillsDir?: string,
+  emit?: (event: ProviderEvent) => void,
+): Promise<string> {
+  if (!prompt) {
+    return prompt;
+  }
+
+  // Split on the FIRST newline only; the remainder is preserved verbatim.
+  const newlineIdx = prompt.indexOf("\n");
+  const firstLineRaw = newlineIdx === -1 ? prompt : prompt.slice(0, newlineIdx);
+  const rest = newlineIdx === -1 ? "" : prompt.slice(newlineIdx + 1);
+
+  // Detect the @skills: command on the first line (trimmed — tolerate leading ws).
+  const match = SKILL_COMMAND_REGEX.exec(firstLineRaw.trim());
+  if (!match || !match[1]) {
+    return prompt;
+  }
+
+  const commandName: string = match[1];
+  const trailingArgs: string = match[2] ?? "";
+  const dir = skillsDir ?? defaultSkillsDir();
+  const skillPath = join(dir, commandName, "SKILL.md");
+
+  const file = Bun.file(skillPath);
+  const exists = await file.exists();
+  if (!exists) {
+    emit?.({
+      type: "raw_stderr",
+      content: `[devin] skill resolver: SKILL.md not found for @skills:${commandName} (looked in ${skillPath})\n`,
+    });
+    return prompt;
+  }
+
+  let skillContent: string;
+  try {
+    skillContent = await file.text();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    emit?.({
+      type: "raw_stderr",
+      content: `[devin] skill resolver: failed to read SKILL.md for @skills:${commandName}: ${message}\n`,
+    });
+    return prompt;
+  }
+
+  if (skillContent.length > MAX_SKILL_CHARS) {
+    emit?.({
+      type: "raw_stderr",
+      content: `[devin] skill resolver: SKILL.md for @skills:${commandName} exceeds ${MAX_SKILL_CHARS} chars (${skillContent.length}), truncating\n`,
+    });
+    skillContent = skillContent.slice(0, MAX_SKILL_CHARS);
+  }
+
+  // Assemble the user-request body: trailing args from the @skills: line (if any),
+  // plus any subsequent lines from the original prompt.
+  const userRequestBody = trailingArgs && rest ? `${trailingArgs}\n${rest}` : trailingArgs || rest;
+
+  return `${skillContent}\n\n---\n\nUser request: ${userRequestBody}`;
+}

package/src/providers/index.ts

@@ -5,10 +5,13 @@ export type {
   ProviderResult,
   ProviderSession,
   ProviderSessionConfig,
+  ProviderTraits,
 } from "./types";
 
 import { ClaudeAdapter } from "./claude-adapter";
+import { ClaudeManagedAdapter } from "./claude-managed-adapter";
 import { CodexAdapter } from "./codex-adapter";
+import { DevinAdapter } from "./devin-adapter";
 import { PiMonoAdapter } from "./pi-mono-adapter";
 import type { ProviderAdapter } from "./types";
 
@@ -21,7 +24,13 @@ export function createProviderAdapter(provider: string): ProviderAdapter {
       return new PiMonoAdapter();
     case "codex":
       return new CodexAdapter();
+    case "claude-managed":
+      return new ClaudeManagedAdapter();
+    case "devin":
+      return new DevinAdapter();
     default:
-      throw new Error(`Unknown HARNESS_PROVIDER: "${provider}". Supported: claude, pi, codex`);
+      throw new Error(
+        `Unknown HARNESS_PROVIDER: "${provider}". Supported: claude, pi, codex, devin, claude-managed`,
+      );
   }
 }

package/src/providers/pi-mono-adapter.ts

@@ -155,7 +155,7 @@ class PiMonoSession implements ProviderSession {
     this._sessionId = agentSession.sessionId;
 
     // Emit session_init immediately
-    this.emit({ type: "session_init", sessionId: this._sessionId });
+    this.emit({ type: "session_init", sessionId: this._sessionId, provider: "pi" });
 
     // Subscribe to agent events and normalize
     this.agentSession.subscribe((event) => this.handleAgentEvent(event));
@@ -364,6 +364,7 @@ class PiMonoSession implements ProviderSession {
       numTurns: stats.userMessages + stats.assistantMessages,
       model: this.agentSession.model?.name ?? this.config.model,
       isError: false,
+      provider: "pi",
     };
   }
 
@@ -391,6 +392,7 @@ class PiMonoSession implements ProviderSession {
 
 export class PiMonoAdapter implements ProviderAdapter {
   readonly name = "pi";
+  readonly traits = { hasMcp: true, hasLocalEnvironment: true };
   private lastCwd = ".";
 
   async createSession(config: ProviderSessionConfig): Promise<ProviderSession> {