@desplega.ai/agent-swarm 2.0.0 → 2.1.0

package/src/be/seed-scripts/catalog/heartbeat-jev-gate.ts

@@ -0,0 +1,368 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  leadAgentId: z.string().optional().describe("Lead agent id; the heartbeat passes it"),
+  dryRun: z
+    .boolean()
+    .optional()
+    .describe(
+      "Return the verdict, the compact state and the prompt it would create, without creating a prompt or writing KV",
+    ),
+  threshold: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe("Quiet when Jev's p(needs action) is below this (default 0.5)"),
+  provider: z
+    .enum(["auto", "typesafe", "openrouter"])
+    .optional()
+    .describe("Jev host; auto prefers TypeSafe (default auto)"),
+  timeZone: z
+    .string()
+    .optional()
+    .describe("IANA time zone for the state's current time and dates (default UTC)"),
+  jevTimeoutMs: z
+    .number()
+    .int()
+    .min(1_000)
+    .max(45_000)
+    .optional()
+    .describe("Abandon the Jev call after this many ms (default 25000); the gate deadline is 60 s"),
+});
+
+const KV_NAMESPACE = "heartbeat-jev-gate";
+const KV_KEY = "setup";
+// Measured per decision in the 2026-10-15 heartbeat replay (229 states).
+const COST_PER_DECISION = "$0.00004";
+
+// Jev is called through `ctx.swarm.systemOne_decide`: the API server reads the
+// key and sends the request, so no key ever enters this script's realm. The
+// server also refuses OpenRouter when the effective OPENROUTER_BASE_URL (stored
+// config or deployment env) points at a gateway.
+const PROVIDERS = {
+  typesafe: { keyName: "TYPESAFE_API_KEY", model: "jev-latest" },
+  openrouter: { keyName: "OPENROUTER_API_KEY", model: "~typesafe/jev-latest" },
+} as const;
+type ProviderId = keyof typeof PROVIDERS;
+
+// Worded exactly as in the replay that set the 0.5 threshold; changing it voids that result.
+const QUESTIONS = {
+  act: {
+    type: "noul",
+    instructions:
+      "This is a 30-minute heartbeat for the Lead agent of an AI agent swarm. Does this state require the Lead to take an action now: message a human, dispatch, resume or fix a task, or act on a tracked item that is due now? Answer false when nothing changed since the previous heartbeat and every failure is already triaged or owned.",
+    criteria: {
+      true: "A new untriaged failure, a tracked item or human ask due now and not yet done, or a problem with no owner",
+      false:
+        "Same state as the previous heartbeat, failures already triaged or owned, nothing due now",
+    },
+  },
+};
+
+type SetupState = {
+  status: "asked" | "approved" | "declined" | "expired";
+  requestId?: string;
+  url?: string;
+  askedAt?: string;
+  resolvedAt?: string;
+};
+
+function rows(res: any): any[] {
+  const p = res?.data ?? res;
+  if (p?.error) throw new Error(`db_query: ${String(p.error).slice(0, 200)}`);
+  if (!Array.isArray(p?.rows)) throw new Error("db_query returned no rows array");
+  const cols: string[] = p.columns ?? [];
+  return p.rows.map((r: any) =>
+    Array.isArray(r) ? Object.fromEntries(cols.map((c, i) => [c, r[i]])) : r,
+  );
+}
+
+const oneLine = (s: unknown) => String(s ?? "").replace(/\s+/g, " ");
+
+/** `YYYY-MM-DD HH:MM` in the zone, falling back to UTC when the runtime has no Intl zone data. */
+function localStamp(ms: number, timeZone: string): { stamp: string; zone: string } {
+  const utc = { stamp: new Date(ms).toISOString().slice(0, 16).replace("T", " "), zone: "UTC" };
+  if (timeZone === "UTC") return utc;
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(new Date(ms));
+    const v = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+    return { stamp: `${v("year")}-${v("month")}-${v("day")} ${v("hour")}:${v("minute")}`, zone: timeZone };
+  } catch {
+    return utc;
+  }
+}
+
+// The checklist task renders failures as these lines (gatherSystemStatus in
+// src/heartbeat/heartbeat.ts). The replay parsed them with this regex, so the
+// gate renders and parses the same way to keep its fields identical.
+const FAILURE_LINE_RE =
+  /- \[([0-9a-f]{8})\] "([\s\S]*?)" — agent: ([0-9a-f]{8}), reason: ([\s\S]*?), at: (\S+)/g;
+
+function parseFailures(status: string): { id: string; what: string; reason: string }[] {
+  const out: { id: string; what: string; reason: string }[] = [];
+  for (const m of status.matchAll(FAILURE_LINE_RE)) {
+    out.push({
+      id: m[1] ?? "",
+      what: oneLine(m[2]).slice(0, 90),
+      reason: oneLine(m[4]).slice(0, 140),
+    });
+  }
+  return out;
+}
+
+function renderFailureLine(t: any): string {
+  const agent = t.agentId ? String(t.agentId).slice(0, 8) : "unassigned";
+  const reason = t.failureReason ? String(t.failureReason).slice(0, 100) : "no reason";
+  return `- [${String(t.id).slice(0, 8)}] "${String(t.task ?? "").slice(0, 50)}" — agent: ${agent}, reason: ${reason}, at: ${t.finishedAt}`;
+}
+
+/**
+ * The compact state Jev scores: the fields of the 2026-10-15 replay, built from
+ * live data because the checklist task body does not exist yet at gate time.
+ */
+async function buildState(ctx: any, leadId: string, nowMs: number, timeZone: string) {
+  const q = async (sql: string, params: unknown[] = []) =>
+    rows(await ctx.swarm.db_query({ sql, params }));
+  const since6h = new Date(nowMs - 6 * 3600e3).toISOString();
+  const since24h = new Date(nowMs - 24 * 3600e3).toISOString();
+  // Sequential: db_query caps concurrent queries per caller, and parallel reads fail with
+  // db_query_concurrency_cap on a busy swarm.
+  const lead = await q("SELECT heartbeatMd FROM agents WHERE id = ?", [leadId]);
+  const prev = await q(
+    `SELECT id, substr(output, 1, 400) AS output,
+            substr(task, 1, instr(task, '## Your Standing Orders')) AS status
+       FROM agent_tasks
+      WHERE agentId = ? AND taskType = 'heartbeat-checklist' AND status = 'completed'
+      ORDER BY createdAt DESC LIMIT 1`,
+    [leadId],
+  );
+  const failed = await q(
+    `SELECT id, agentId, substr(task, 1, 60) AS task, substr(failureReason, 1, 120) AS failureReason, finishedAt
+       FROM agent_tasks WHERE status = 'failed' AND finishedAt > ?
+      ORDER BY finishedAt DESC LIMIT 10`,
+    [since6h],
+  );
+  const overview = await q(
+    `SELECT SUM(status = 'in_progress') AS inProgress, SUM(status = 'pending') AS pending,
+            SUM(status = 'unassigned') AS unassigned,
+            SUM(status = 'completed' AND finishedAt > ?) AS completed24,
+            SUM(status = 'failed' AND finishedAt > ?) AS failed24
+       FROM agent_tasks`,
+    [since24h, since24h],
+  );
+  const agents = await q(
+    "SELECT status, COUNT(*) AS n FROM agents WHERE COALESCE(role, '') != 'extension' GROUP BY status",
+  );
+
+  const fails = parseFailures(failed.map(renderFailureLine).join("\n"));
+  const prevIds = new Set(parseFailures(String(prev[0]?.status ?? "")).map((f) => f.id));
+  const newFails = fails.filter((f) => !prevIds.has(f.id));
+
+  const { stamp, zone } = localStamp(nowMs, timeZone);
+  const mmdd = new Date(nowMs).toISOString().slice(5, 10);
+  const mmddLocal = stamp.slice(5, 10);
+  const due: string[] = [];
+  for (const line of String(lead[0]?.heartbeatMd ?? "").split("\n")) {
+    const l = line.trim();
+    if (!l) continue;
+    const del = /DELETE <?(\d\d-\d\d)>?/.exec(l);
+    if (l.includes(mmdd) || l.includes(mmddLocal) || (del?.[1] && del[1] <= mmddLocal)) {
+      due.push(oneLine(l).slice(0, 200));
+    }
+    if (due.length >= 6) break;
+  }
+
+  const o = overview[0] ?? {};
+  const n = (v: unknown) => Number(v ?? 0) || 0;
+  const count = (s: string) => n(agents.find((a) => a.status === s)?.n);
+  const idle = count("idle");
+  const busy = count("busy");
+
+  return {
+    now: `${stamp} ${zone}`,
+    new_failures_since_previous_heartbeat: newFails.length
+      ? newFails.map((f) => `${f.id}: ${f.what} | ${f.reason}`)
+      : "none",
+    tracked_items_mentioning_today_or_past_delete_date: due.length ? due : "none",
+    previous_heartbeat_result: prev[0]?.output
+      ? oneLine(prev[0].output).slice(0, 350)
+      : "unknown",
+    failures_last_6h_total: fails.length,
+    task_overview: `- In Progress: ${n(o.inProgress)} - Pending: ${n(o.pending)} - Unassigned: ${n(o.unassigned)} - Completed (24h): ${n(o.completed24)} - Failed (24h): ${n(o.failed24)}`,
+    agents: `- Online: ${idle + busy} (${idle} idle, ${busy} busy), Offline: ${count("offline")}`,
+  };
+}
+
+function setupPrompt(keys: string[]) {
+  return {
+    title: "Heartbeat Jev gate: add a Jev credential or decline",
+    detached: true,
+    questions: [
+      {
+        id: "enable",
+        type: "approval",
+        label: "Enable the Jev heartbeat gate?",
+        description: [
+          "Before each recurring heartbeat checklist, the `heartbeat-jev-gate` script sends a short summary of swarm state (about 1,500 characters: new failures, due tracked items, task and agent counts) to Jev, a small decision model by TypeSafe, and asks whether the Lead needs to act. With `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`, quiet ticks skip the Lead's checklist task.",
+          "",
+          `Cost: about ${COST_PER_DECISION} per decision, one decision per checklist tick.`,
+          "",
+          `No Jev credential is configured. To enable, approve and add one of ${keys.map((k) => `\`${k}\``).join(" or ")} as a global secret on the Secrets page (Settings > Secrets). Do not paste the key here. The next tick picks it up.`,
+          "",
+          "Reject to decline. The gate then stays inactive, with no further prompts, until a key is added.",
+        ].join("\n"),
+      },
+    ],
+  };
+}
+
+/**
+ * Heartbeat checklist gate backed by Jev: asks Jev whether a recurring checklist
+ * tick needs the Lead and returns { quiet, reason, summary }. With no Jev
+ * credential it asks a human once, then stays a no-op until a key is added.
+ */
+export default async function heartbeatJevGate(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args ?? {});
+  if (!parsed.success) throw new Error(`invalid args: ${parsed.error.message.slice(0, 200)}`);
+  const a = parsed.data;
+  const dryRun = a.dryRun === true;
+
+  const agentInfo: any = a.leadAgentId ? null : await ctx.swarm.agent_info();
+  const leadId = String(a.leadAgentId ?? agentInfo?.data?.id ?? agentInfo?.id ?? "");
+  if (!leadId) throw new Error("no leadAgentId");
+
+  // Values of secret rows come back masked: presence is all this script reads.
+  const cfgRes: any = await ctx.swarm.config_get({ agentId: leadId });
+  const configs: any[] = cfgRes?.data?.configs ?? cfgRes?.configs ?? [];
+  const cfg = (key: string): string => {
+    const value = configs.find((c) => c?.key === key)?.value;
+    return typeof value === "string" ? value.trim() : "";
+  };
+
+  const cfgThreshold = Number.parseFloat(cfg("HEARTBEAT_JEV_GATE_THRESHOLD"));
+  const threshold =
+    a.threshold ?? (cfgThreshold >= 0 && cfgThreshold <= 1 ? cfgThreshold : 0.5);
+  const providerPref = a.provider ?? (cfg("HEARTBEAT_JEV_GATE_PROVIDER").toLowerCase() || "auto");
+  const timeZone = a.timeZone ?? (cfg("HEARTBEAT_JEV_GATE_TIMEZONE") || "UTC");
+
+  const usable: Record<ProviderId, boolean> = {
+    typesafe: cfg(PROVIDERS.typesafe.keyName) !== "",
+    openrouter: cfg(PROVIDERS.openrouter.keyName) !== "",
+  };
+  const candidates: ProviderId[] =
+    providerPref === "typesafe"
+      ? ["typesafe"]
+      : providerPref === "openrouter"
+        ? ["openrouter"]
+        : ["typesafe", "openrouter"];
+  const provider = candidates.find((id) => usable[id]);
+
+  if (!provider) {
+    const keys = candidates.map((id) => PROVIDERS[id].keyName);
+    const inactive = (state: string, extra: Record<string, unknown> = {}) => ({
+      quiet: false,
+      reason: `jev-gate inactive: ${state}`.slice(0, 300),
+      ...(dryRun ? { dryRun: true, ...extra } : {}),
+    });
+    const entry: any = await ctx.swarm.kv_getOrNull({ namespace: KV_NAMESPACE, key: KV_KEY });
+    const stored = entry?.value;
+    let setup: SetupState | null = typeof stored === "string" ? JSON.parse(stored) : (stored ?? null);
+
+    if (!setup) {
+      const prompt = setupPrompt(keys);
+      if (dryRun) {
+        const state = await buildState(ctx, leadId, Date.now(), timeZone);
+        return inactive("no credential, would ask a human", { prompt, state });
+      }
+      const res: any = await ctx.swarm.request_humanInput(prompt);
+      const requestId = res?.data?.requestId ?? res?.requestId;
+      if (!requestId) throw new Error("request_humanInput returned no requestId");
+      setup = {
+        status: "asked",
+        requestId,
+        url: res?.data?.url ?? res?.url,
+        askedAt: new Date().toISOString(),
+      };
+      await ctx.swarm.kv_set({ namespace: KV_NAMESPACE, key: KV_KEY, value: setup });
+      return inactive(`no credential, asked a human (approval request ${requestId})`);
+    }
+
+    if (setup.status === "asked" && setup.requestId) {
+      const [req] = rows(
+        await ctx.swarm.db_query({
+          sql: "SELECT status FROM approval_requests WHERE id = ?",
+          params: [setup.requestId],
+        }),
+      );
+      const status = String(req?.status ?? "missing");
+      if (status === "pending") {
+        return inactive(`no credential, awaiting answer on approval request ${setup.requestId}`);
+      }
+      const next: SetupState["status"] =
+        status === "approved" ? "approved" : status === "rejected" ? "declined" : "expired";
+      setup = { ...setup, status: next, resolvedAt: new Date().toISOString() };
+      if (!dryRun) await ctx.swarm.kv_set({ namespace: KV_NAMESPACE, key: KV_KEY, value: setup });
+    }
+
+    const why =
+      setup.status === "approved"
+        ? `approved, waiting for ${keys.join(" or ")} on the Secrets page`
+        : setup.status === "declined"
+          ? `declined; add ${keys.join(" or ")} to enable`
+          : `setup request expired unanswered; add ${keys.join(" or ")} to enable`;
+    return inactive(why, { setup });
+  }
+
+  const target = PROVIDERS[provider];
+  const state = await buildState(ctx, leadId, Date.now(), timeZone);
+
+  // The server enforces the time budget. No retries, as in the replay.
+  const res: any = await ctx.swarm.systemOne_decide({
+    provider,
+    model: target.model,
+    state,
+    questions: QUESTIONS,
+    timeoutMs: a.jevTimeoutMs ?? 25_000,
+    maxRetries: 0,
+  });
+  const body: any = res?.data ?? res;
+  if (res?.success === false || body?.success === false) {
+    throw new Error(`jev ${provider}: ${String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 250)}`);
+  }
+  const p = body?.answers?.act?.noul;
+  if (typeof p !== "number" || !Number.isFinite(p)) {
+    throw new Error(`jev ${provider}: response has no numeric answers.act.noul`);
+  }
+
+  const pText = p.toFixed(3);
+  const quiet = p < threshold;
+  const verdict: Record<string, unknown> = {
+    quiet,
+    reason: `jev p(needs action)=${pText} ${quiet ? "<" : ">="} ${threshold} via ${provider}`,
+  };
+  if (!quiet) {
+    const lines = [`Jev p(needs action) = ${pText} (threshold ${threshold}, ${provider}).`];
+    const failures = state.new_failures_since_previous_heartbeat;
+    const tracked = state.tracked_items_mentioning_today_or_past_delete_date;
+    if (Array.isArray(failures)) {
+      lines.push("", "New failures since the previous checklist:", ...failures.map((f) => `- ${f}`));
+    }
+    if (Array.isArray(tracked)) {
+      lines.push("", "Tracked items due today or past their DELETE date:", ...tracked.map((t) => `- ${t.replace(/^[-*] /, "")}`));
+    }
+    if (!Array.isArray(failures) && !Array.isArray(tracked)) {
+      lines.push("", "No new failures or due tracked items; Jev flagged the overall state.");
+    }
+    verdict.summary = lines.join("\n").slice(0, 4000);
+  }
+  return dryRun ? { ...verdict, dryRun: true, provider, p, threshold, state } : verdict;
+}

package/src/be/seed-scripts/index.ts

@@ -35,6 +35,7 @@ import getChildOutputsSrc from "./catalog/get-child-outputs.ts" with { type: "te
 import ghPrSnapshotSrc from "./catalog/gh-pr-snapshot.ts" with { type: "text" };
 import githubIssuesPullSrc from "./catalog/github-issues-pull.ts" with { type: "text" };
 import groupCountSrc from "./catalog/group-count.ts" with { type: "text" };
+import heartbeatJevGateSrc from "./catalog/heartbeat-jev-gate.ts" with { type: "text" };
 import jsonQuerySrc from "./catalog/json-query.ts" with { type: "text" };
 import linearIssueSrc from "./catalog/linear-issue.ts" with { type: "text" };
 import memoryDedupCheckSrc from "./catalog/memory-dedup-check.ts" with { type: "text" };
@@ -112,6 +113,14 @@ export const SEED_SCRIPTS: SeedScript[] = [
       "Keep an app's synced rows fresh on a schedule or on demand; the script a targetType:'script' schedule points at to sync an app.",
     source: asText(appSyncRunSrc),
   },
+  {
+    name: "heartbeat-jev-gate",
+    description:
+      "Heartbeat checklist gate backed by Jev (TypeSafe or OpenRouter decisions API): scores a compact swarm state and returns {quiet, reason, summary} for HEARTBEAT_CHECKLIST_GATE_SCRIPT.",
+    intent:
+      "Skip quiet Lead heartbeat checklist ticks with a cheap Jev decision; with no Jev credential it asks a human once, then stays a no-op until a key is added.",
+    source: asText(heartbeatJevGateSrc),
+  },
   {
     name: "fetch-readable",
     description:

package/src/be/swarm-config-guard.ts

@@ -455,6 +455,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "SLACK_REACTION_STEERED",
     "SLACK_REACTION_COMPLETED",
     "SLACK_REACTION_FAILED",
+    "SLACK_STATUS_ICON_COMPLETED",
   ]),
   // Counts, minutes, and intervals: positive integers. Deliberately permissive
   // on the upper bound — an operator raising a sweep cap is legitimate.

package/src/commands/runner.ts

@@ -101,6 +101,7 @@ import { refreshSkillsIfChanged } from "../utils/skills-refresh.ts";
 import { guardSpawnModel } from "../utils/spawn-model-guard.ts";
 import { isSteeringEnabled } from "../utils/steering-enabled.ts";
 import { interpolate } from "../utils/template.ts";
+import { vcsRepoName, vcsRepoUrlMatches } from "../utils/vcs-repo-match.ts";
 import {
   canonicalAzureDevOpsRepoUrl,
   isAzureDevOpsUrl,
@@ -212,11 +213,7 @@ export async function fetchRepoConfig(
   guidelines?: RepoGuidelines | null;
 } | null> {
   try {
-    const requested = vcsRepo
-      .trim()
-      .replace(/\/+$/, "")
-      .replace(/\.git$/, "");
-    const repoName = requested.split("/").pop() || requested;
+    const repoName = vcsRepoName(vcsRepo);
     const resp = await fetch(`${apiUrl}/api/repos?name=${encodeURIComponent(repoName)}`, {
       headers: { Authorization: `Bearer ${apiKey}` },
     });
@@ -233,18 +230,7 @@ export async function fetchRepoConfig(
       }>;
     };
     if (requireExactMatch) {
-      return (
-        data.repos.find((r) => {
-          const normalized = r.url
-            .trim()
-            .replace(/\/+$/, "")
-            .replace(/\.git$/, "");
-          if (normalized === requested) return true;
-          // Qualified URLs must retain their host. Only shorthand references use suffix matching.
-          if (requested.includes(":")) return false;
-          return normalized.endsWith(`/${requested}`) || normalized.endsWith(`:${requested}`);
-        }) ?? null
-      );
+      return data.repos.find((r) => vcsRepoUrlMatches(r.url, vcsRepo)) ?? null;
     }
     return data.repos.find((r) => r.url.includes(vcsRepo)) ?? data.repos[0] ?? null;
   } catch {

package/src/extensions/catalog.generated.json

@@ -1,4 +1,21 @@
 {
+  "comms-adherence-gate": {
+    "manifestFile": "manifest.json",
+    "manifest": {
+      "$schema": "../manifest.schema.json",
+      "name": "comms-adherence-gate",
+      "description": "Judges every Slack-facing store-progress completion against the requester's comms preferences and latest request with Jev (TypeSafe or OpenRouter), and in enforce blocks a non-adherent completion once per task",
+      "version": "1.5.0",
+      "runtime": "api",
+      "assets": {
+        "hooks": "hooks.ts"
+      }
+    },
+    "files": {
+      "hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * comms-adherence-gate\n *\n * When an agent calls `store-progress` with status \"completed\" on a task that\n * reaches a human in Slack, judge the `output` against the requesting user's\n * stored comms preferences (users.metadata.$.comms) with Jev, and against what\n * that user actually asked for in their latest message. An explicit request\n * (\"tell me a long joke\", \"explain in detail\") outranks the stored default, so\n * a requested long answer is not a verbosity failure.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode):\n *   off     -> never evaluate\n *   shadow  -> evaluate + record, never block (default)\n *   enforce -> record, and block the completion up to maxBlocksPerTask times\n *              per task with actionable feedback\n *\n * Fails OPEN on every error: a judge outage must never wall the swarm.\n * Every verdict lands in KV namespace `ext:comms-gate`.\n */\n\nexport const config = z.object({\n  mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  /** A dimension scoring below this fails. */\n  threshold: z.number().min(0).max(1).default(0.5),\n  timeoutMs: z.number().int().positive().default(4000),\n  maxBlocksPerTask: z.number().int().min(0).default(1),\n  provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n  /** Jev model on the TypeSafe transport. */\n  model: z.string().default(\"jev-latest\"),\n  /** Jev model on the OpenRouter transport. */\n  openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n  /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n  apiKey: z.string().optional(),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:comms-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst UUID_RE = /^[0-9a-fA-F-]{36}$/;\n// The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const cfgOf = (raw: unknown): Cfg => {\n  const parsed = config.safeParse(raw ?? {});\n  return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n  (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._-]/g, \"_\").slice(0, 120);\n\n/** SDK envelopes: {success, data:{...}} or the bare payload. */\ntype Envelope = {\n  data?: { rows?: unknown[]; value?: unknown };\n  rows?: unknown[];\n  value?: unknown;\n} | null;\n\nconst cell = (row: unknown, i: number, key: string): unknown =>\n  Array.isArray(row) ? row[i] : (row as Record<string, unknown>)?.[key];\n\n/**\n * The newest human message sits at the END of a Slack task: the\n * `<thread_context>` blob comes first and can run to thousands of chars, so a\n * leading slice of `agent_tasks.task` shows the judge everything except the\n * actual request. Take the tail, then the part after the last `</thread_context>`.\n */\nconst CTX_END = \"</thread_context>\";\nexport const latestAsk = (tail: string): string => {\n  const end = tail.lastIndexOf(CTX_END);\n  let out = (end >= 0 ? tail.slice(end + CTX_END.length) : tail)\n    .replace(/\\[Thread follow-up[^\\]]*\\]/g, \"\")\n    .trim();\n  // Some tasks end with the context block; fall back to the last messages in it.\n  if (out.length < 8) out = (end >= 0 ? tail.slice(0, end) : tail).trim().slice(-800);\n  return out.slice(0, 900);\n};\n\n// Preferences are the DEFAULT. A direct request outranks them.\nconst JUDGING_RULES = [\n  \"The requester's explicit instruction in latest_request OUTRANKS requester_preferences. Preferences describe the DEFAULT; they never override a direct request.\",\n  \"If latest_request asks for something long, detailed, creative, a story, a joke, a full explanation or a document, then length and structure serving that request are CORRECT and must NOT be penalized.\",\n  \"Judge whether agent_message serves what latest_request actually asked for, written in the requester's manner. Do not judge it against the default preference when the request overrides it.\",\n];\n\ntype Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;\n\n/** One `noul` question per stated preference the gate knows how to judge. */\nexport const buildQuestions = (prefs: Prefs): Record<string, unknown> => {\n  const questions: Record<string, unknown> = {};\n  if (prefs.verbosity) {\n    questions.verbosity = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message respect the requester's verbosity preference, AS OVERRIDDEN by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"Length and structure fit what latest_request asked for (or the stated preference when the request does not override it), and it leads with the result.\",\n        false:\n          \"Too long for what was asked, or it opens with preamble, recaps the request, narrates the process, or ends with an offer to elaborate. Length explicitly requested in latest_request is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.tone) {\n    questions.tone = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message match the requester's stated tone preference, as overridden by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"The tone matches what the requester asked for.\",\n        false:\n          \"The tone conflicts with it (for example hedging, flattery or filler when the requester asked for direct and plain). A voice appropriate to an explicitly requested creative or narrative form is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.language) {\n    questions.language = {\n      type: \"noul\",\n      instructions: \"Is agent_message written in the requester's stated language?\",\n      criteria: {\n        true: \"Written in the stated language.\",\n        false: \"Written in a different language.\",\n      },\n    };\n  }\n  return questions;\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n  const cached = secretCache.get(name);\n  if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n  const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n  if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n  return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n  secretCache.clear();\n};\n\nexport type JevTransport = {\n  provider: \"typesafe\" | \"openrouter\";\n  endpoint: string;\n  key: string;\n  model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n  const typesafe = (): JevTransport | null => {\n    const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n    return usable(key)\n      ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n      : null;\n  };\n  const openrouter = (): JevTransport | null => {\n    const key = secret(\"OPENROUTER_API_KEY\");\n    return usable(key)\n      ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n      : null;\n  };\n  const transport =\n    cfg.provider === \"typesafe\"\n      ? typesafe()\n      : cfg.provider === \"openrouter\"\n        ? openrouter()\n        : (typesafe() ?? openrouter());\n  if (transport) return transport;\n  throw new Error(\n    cfg.provider === \"typesafe\"\n      ? \"no TYPESAFE_API_KEY\"\n      : cfg.provider === \"openrouter\"\n        ? \"no OPENROUTER_API_KEY\"\n        : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n  );\n};\n\n/** One Jev call; returns the `noul` score per question. Throws on any failure. */\nexport const askJev = async (\n  state: Record<string, unknown>,\n  questions: Record<string, unknown>,\n  transport: JevTransport,\n  cfg: Cfg,\n  outer?: AbortSignal,\n): Promise<{ scores: Record<string, number>; latencyMs: number }> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n  const onOuterAbort = () => controller.abort();\n  outer?.addEventListener(\"abort\", onOuterAbort);\n  const t0 = Date.now();\n  try {\n    const res = await fetch(transport.endpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${transport.key}` },\n      body: JSON.stringify({ state, model: transport.model, questions }),\n      signal: controller.signal,\n    });\n    if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n    const body = (await res.json()) as { answers?: Record<string, { noul?: unknown }> } | null;\n    const answers = body?.answers;\n    if (!answers || typeof answers !== \"object\") throw new Error(\"no answers in response\");\n    const scores: Record<string, number> = {};\n    for (const [id, a] of Object.entries(answers)) {\n      if (typeof a?.noul === \"number\") scores[id] = a.noul;\n    }\n    if (Object.keys(scores).length === 0) throw new Error(\"no scores in response\");\n    return { scores, latencyMs: Date.now() - t0 };\n  } finally {\n    clearTimeout(timer);\n    outer?.removeEventListener(\"abort\", onOuterAbort);\n  }\n};\n\nconst SELFTEST = \"comms-gate-selftest\";\nconst SELFTEST_PREFS = {\n  tone: \"direct, plain, no hedging\",\n  language: \"English\",\n  verbosity:\n    \"very terse - answer in the first sentence, ~400 chars max. No preamble, no recap, no closing offer.\",\n};\nconst SELFTEST_BAD =\n  \"Great question! Let me walk you through what I did here. First I looked at the task, then I reviewed the relevant files, and after careful consideration I decided to go with option B. I hope this helps - let me know if you would like me to elaborate further on any of the above!\";\nconst SELFTEST_GOOD =\n  \"Went with option B: it is the only one that keeps the migration reversible. PR #123.\";\n\n/**\n * Run the judge on a known-bad (positive control, must score below threshold) and a\n * known-good (negative control, must score at or above it) message and record both\n * under `selftest:last`. Proves key, egress and KV from inside the API runtime\n * without touching real traffic.\n */\nconst selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {\n  const started = Date.now();\n  try {\n    const transport = resolveTransport(cfg);\n    const questions = { verbosity: buildQuestions(SELFTEST_PREFS).verbosity };\n    const judge = (message: string) =>\n      askJev(\n        { requester_preferences: SELFTEST_PREFS, agent_message: message },\n        questions,\n        transport,\n        cfg,\n        signal,\n      ).then((r) => r.scores.verbosity ?? null);\n    const [bad, good] = await Promise.all([judge(SELFTEST_BAD), judge(SELFTEST_GOOD)]);\n    await swarm.kv_set({\n      namespace: NS,\n      key: \"selftest:last\",\n      value: {\n        at: new Date().toISOString(),\n        provider: transport.provider,\n        threshold: cfg.threshold,\n        positiveControlBadScore: bad,\n        negativeControlGoodScore: good,\n        controlsOk:\n          typeof bad === \"number\" &&\n          typeof good === \"number\" &&\n          bad < cfg.threshold &&\n          good >= cfg.threshold,\n        latencyMs: Date.now() - started,\n      },\n    });\n  } catch (err) {\n    await swarm\n      .kv_set({\n        namespace: NS,\n        key: \"selftest:last\",\n        value: {\n          at: new Date().toISOString(),\n          error: String(err).slice(0, 400),\n          latencyMs: Date.now() - started,\n        },\n      })\n      .catch(() => {});\n  }\n};\n\nconst TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,\n       json_extract(u.metadata, '$.comms') AS comms, u.name,\n       substr(t.task, 1, 400) AS askHead,\n       substr(t.task, -1400) AS askTail\nFROM agent_tasks t\nLEFT JOIN users u ON u.id = t.requestedByUserId\nWHERE t.id = ?`;\n\nconst LEAD_SQL = \"SELECT isLead FROM agents WHERE id = ?\";\n\n/**\n * Mirrors the `task.progress.write` rule store-progress enforces\n * (src/rbac/legacy-policy.ts): the caller owns the task, the task is\n * unassigned, or the caller is a lead. Lead status comes from the caller's\n * agents row, never from tool args. Extension callers return before this.\n */\nconst mayWriteProgress = async (\n  swarm: Swarm,\n  callerId: string | undefined,\n  taskAgentId: string,\n): Promise<boolean> => {\n  if (!callerId) return false;\n  if (!taskAgentId || taskAgentId === callerId) return true;\n  const q = (await swarm.db_query({ sql: LEAD_SQL, params: [callerId] })) as Envelope;\n  const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n  return Number(cell(row, 0, \"isLead\") ?? 0) === 1;\n};\n\nconst extension: SwarmExtension = (api) => {\n  api.on(\"pre.tool.call\", async (event, ctx) => {\n    if (event.tool !== \"store-progress\") return;\n    if (event.requestInfo?.callOrigin === \"extension\") return;\n\n    const cfg = cfgOf(ctx.config);\n    if (cfg.mode === \"off\") return;\n\n    const args = (event.args ?? {}) as Record<string, unknown>;\n\n    // Self-test hatch: a progress call whose text starts with the sentinel runs\n    // the controls and records them under `selftest:last`.\n    if (args.status !== \"completed\") {\n      if (typeof args.progress === \"string\" && args.progress.startsWith(SELFTEST)) {\n        await selfTest(ctx.swarm, cfg, ctx.signal);\n      }\n      return;\n    }\n\n    const output = typeof args.output === \"string\" ? args.output.trim() : \"\";\n    if (!output) return;\n\n    const taskId = String(args.taskId ?? event.requestInfo?.sourceTaskId ?? \"\");\n    if (!UUID_RE.test(taskId)) return;\n\n    try {\n      const q = (await ctx.swarm.db_query({ sql: TASK_SQL, params: [taskId] })) as Envelope;\n      const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n      if (!row) return;\n\n      const source = String(cell(row, 0, \"source\") ?? \"\");\n      const slackThreadTs = cell(row, 1, \"slackThreadTs\");\n      const agentId = String(cell(row, 2, \"agentId\") ?? \"\");\n      const requesterId = String(cell(row, 3, \"requestedByUserId\") ?? \"\");\n      const commsRaw = cell(row, 4, \"comms\");\n      const requesterName = String(cell(row, 5, \"name\") ?? requesterId);\n      const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n      const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n      // Judge only a completion store-progress will accept, so no agent can ship\n      // another task's thread and preferences to the external judge.\n      if (!(await mayWriteProgress(ctx.swarm, event.requestInfo?.agentId, agentId))) return;\n\n      // Only where the text actually reaches a human in Slack.\n      if (source !== \"slack\" && !slackThreadTs) return;\n      if (!commsRaw) return; // no stated preferences -> nothing to judge against\n      const prefs = (typeof commsRaw === \"string\" ? JSON.parse(commsRaw) : commsRaw) as Prefs;\n      if (!prefs || typeof prefs !== \"object\") return;\n\n      const questions = buildQuestions(prefs);\n      if (Object.keys(questions).length === 0) return;\n\n      const transport = resolveTransport(cfg);\n      const { scores, latencyMs } = await askJev(\n        {\n          role: \"You audit an AI agent's final message to the human who requested the work.\",\n          requester: requesterName,\n          requester_preferences: prefs,\n          latest_request: ask,\n          thread_opening: threadOpening,\n          judging_rules: JUDGING_RULES,\n          agent_message: output,\n        },\n        questions,\n        transport,\n        cfg,\n        ctx.signal,\n      );\n\n      const failed = Object.entries(scores)\n        .filter(([, v]) => v < cfg.threshold)\n        .map(([k]) => k);\n\n      const verdict = {\n        at: new Date().toISOString(),\n        taskId,\n        agentId,\n        source,\n        requester: requesterName,\n        requesterId,\n        provider: transport.provider,\n        scores,\n        failed,\n        threshold: cfg.threshold,\n        mode: cfg.mode,\n        latencyMs,\n        preferences: prefs,\n        askPreview: ask.slice(0, 400),\n        outputPreview: output.slice(0, 700),\n      };\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"total\" });\n      await ctx.swarm.kv_set({ namespace: NS, key: \"last\", value: verdict });\n\n      if (failed.length === 0) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"pass\" });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"fail\" });\n      for (const dim of failed) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: `dim:${safeKey(dim)}` });\n      }\n\n      const blocksKey = `blocks:${safeKey(taskId)}`;\n      // kv_get answers {success, data:{value}}, and {success:false} when absent.\n      const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;\n      const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;\n      const willBlock = cfg.mode === \"enforce\" && priorBlocks < cfg.maxBlocksPerTask;\n\n      await ctx.swarm.kv_set({\n        namespace: NS,\n        key: `fail:${Date.now()}:${safeKey(taskId)}`,\n        value: { ...verdict, action: willBlock ? \"blocked\" : \"recorded\" },\n      });\n\n      if (!willBlock) {\n        await ctx.swarm.kv_incr({\n          namespace: NS,\n          key: cfg.mode === \"enforce\" ? \"escaped\" : \"shadowed\",\n        });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"blocked\" });\n      await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });\n\n      const detail = failed\n        .map(\n          (d) =>\n            `${d} (${scores[d]!.toFixed(2)} vs ${cfg.threshold}) — requested: ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n        )\n        .join(\"\\n\");\n\n      return block(\n        [\n          `Comms gate: this output does not match ${requesterName}'s stated preferences.`,\n          detail,\n          \"Rewrite the output to match and call store-progress again. Do not change the facts, only how they are said.\",\n        ].join(\"\\n\"),\n      );\n    } catch (err) {\n      // Fail open, always.\n      try {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"error\" });\n        await ctx.swarm.kv_set({\n          namespace: NS,\n          key: \"error:last\",\n          value: { at: new Date().toISOString(), taskId, error: String(err).slice(0, 400) },\n        });\n      } catch {\n        /* ignore */\n      }\n      ctx.log.warn(\"comms-adherence-gate: failing open\", { error: String(err) });\n      return;\n    }\n  });\n};\n\nexport default extension;\n"
+    },
+    "readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads. This extension judges that message against the requester's stated comms preferences and their latest request with Jev, [TypeSafe](https://typesafe.ai)'s decision model. In `enforce` it blocks a non-adherent completion once and tells the agent what to fix.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the `store-progress` call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |\n\n## What it gates\n\nHook: `pre.tool.call` on `store-progress` with `status: \"completed\"` and a non-empty `output`. Calls made by extensions are skipped. The task must:\n\n1. Come from Slack (`source = \"slack\"` or a `slackThreadTs`). Other tasks pass without a Jev call.\n2. Have a requester with stated preferences in `users.metadata.comms`. A requester with none passes. Set them with the `manage-user` tool.\n\n## Decision\n\nThe gate reads the task row and asks one `noul` question per stated preference it knows: `verbosity`, `tone`, `language`. Any other key in `comms` is context only.\n\nJev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.\n\nA dimension fails when its score is below `threshold`. Any failed dimension fails the output.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nEach verdict row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the completion through: a missing key, an HTTP error, a network error, a timeout, a malformed answer, or a failed DB read. The handler never throws, so an outage cannot auto-disable the extension. Each failure bumps the `error` counter and overwrites `error:last`.\n\n## Self-test\n\nCall `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference and writes `selftest:last`: both scores, the threshold, the provider, and `controlsOk` (bad below threshold and good at or above it). Real traffic is untouched.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `threshold` | `0.5` | A dimension scoring below this fails |\n| `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n\n## Required secrets\n\nRead from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every completion fails open.\n\nNo key is written to config, KV, logs, or a block reason.\n\n## KV namespace `ext:comms-gate`\n\n- `last`: the latest verdict, with `scores`, `failed`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.\n- `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).\n- `blocks:<taskId>`: blocks issued for that task.\n- `error:last`, `selftest:last`.\n- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (enforce, block budget spent), `shadowed`, `error`, and `dim:<dimension>`.\n\n## Known limits\n\n- Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.\n- The block budget is per task, so a retried completion after a block goes through once the budget is spent, even if it still fails.\n"
+  },
   "deploy-awareness": {
     "manifestFile": "manifest.json",
     "manifest": {

package/src/extensions/contract-types.generated.ts

@@ -1,4 +1,4 @@
 // Generated by scripts/bundle-extension-types.ts. Do not edit.
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: Type declarations contain literal template placeholders.
 export const EXTENSION_TYPE_DEFINITIONS =
-  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';
+  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    resolvedProfile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';