@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/be/users.ts

@@ -615,6 +615,23 @@ export async function mintRuntimeToken(
   return await insertSessionToken(agentId, null, runtimeId, ttlMs);
 }
 
+/**
+ * Mint the short-lived `aseph_` token a script run uses for its `ctx.swarm`
+ * SDK calls, so those calls present the executing agent instead of the swarm
+ * API key (the operator). It resolves as a plain agent principal (`kind:
+ * "agent"`, no task/runtime binding), so the API layer scopes it to that
+ * agent's permissions: a lead keeps lead powers, a worker reads only its own
+ * scope. Marked `scriptRun` so it stays apart from the agent's worker token
+ * (see `AGENT_TOKEN_BINDING`). The run revokes it when it ends; `ttlMs` is the
+ * backstop for a run that dies without revoking.
+ */
+export async function mintScriptRunToken(
+  agentId: string,
+  ttlMs: number,
+): Promise<{ tokenId: string; plaintext: string }> {
+  return await insertSessionToken(agentId, null, null, ttlMs, null, undefined, null, null, true);
+}
+
 export async function insertSessionToken(
   agentId: string,
   taskId: string | null,
@@ -624,6 +641,7 @@ export async function insertSessionToken(
   expiresAtCeiling?: string,
   controllerId: string | null = null,
   parentTokenId: string | null = null,
+  scriptRun = false,
 ): Promise<{ tokenId: string; plaintext: string }> {
   const plaintext = `${SESSION_TOKEN_PREFIX}${base62(randomBytes(24))}`;
   const tokenId = randomUUID().replace(/-/g, "");
@@ -636,8 +654,8 @@ export async function insertSessionToken(
 
   await getDbClient().run(
     `INSERT INTO session_tokens
-     (id, tokenHash, tokenPreview, agentId, taskId, runtimeId, parentRuntimeId, expiresAt, createdAt, controllerId, parentTokenId)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+     (id, tokenHash, tokenPreview, agentId, taskId, runtimeId, parentRuntimeId, expiresAt, createdAt, controllerId, parentTokenId, scriptRun)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     [
       tokenId,
       hash,
@@ -650,6 +668,7 @@ export async function insertSessionToken(
       now.toISOString(),
       controllerId,
       parentTokenId,
+      scriptRun ? 1 : 0,
     ],
   );
 
@@ -713,9 +732,14 @@ export async function revokeRuntimeTokensForRuntime(runtimeId: string): Promise<
 // Agent tokens (long-lived, one agent, no runtime)
 // ---------------------------------------------------------------------------
 
-/** SQL predicate for an agent token: bound to its agent and nothing else. */
+/**
+ * SQL predicate for an agent (worker) token: bound to its agent and nothing
+ * else. `scriptRun = 0` excludes a script run's ephemeral token, which shares
+ * the same all-null binding shape but has its own lifecycle (see migration 233
+ * and `mintScriptRunToken`).
+ */
 const AGENT_TOKEN_BINDING =
-  "taskId IS NULL AND runtimeId IS NULL AND controllerId IS NULL AND parentRuntimeId IS NULL";
+  "taskId IS NULL AND runtimeId IS NULL AND controllerId IS NULL AND parentRuntimeId IS NULL AND scriptRun = 0";
 
 /** Stored expiry of a token that does not expire. `expiresAt` is NOT NULL. */
 export const AGENT_TOKEN_NO_EXPIRY = "9999-12-31T23:59:59.999Z";

package/src/extensions/catalog.generated.json

@@ -4,17 +4,17 @@
     "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",
+      "description": "Judges every Slack-facing store-progress completion and agent Slack post against the comms preferences of the requester, or of the person it @-mentions, their latest request and a plain-language rubric with Jev (TypeSafe or OpenRouter), and in enforce blocks a failing call once per task",
+      "version": "1.7.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"
+      "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, or posts to Slack itself (`slack-reply`,\n * `slack-post`, `slack-start-thread`, `slack-update`), judge the text with Jev:\n * against the requesting user's stored comms preferences\n * (users.metadata.$.comms) and what that user actually asked for in their\n * latest message, and against a plain-language rubric that applies to every\n * message whatever preferences exist. An explicit request (\"tell me a long\n * joke\", \"explain in detail\") outranks the stored default, so a requested long\n * answer is not a verbosity failure.\n *\n * Threads with several people: a message that @-mentions someone is judged\n * against the first mentioned person with stored preferences, skipping a\n * requester without preferences; otherwise against the requester. `plain` applies to everyone.\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 for the preference dimensions, config.plainMode for `plain`):\n *   off     -> never evaluate\n *   shadow  -> evaluate + record, never block (default)\n *   enforce -> record, and block the call up to maxBlocksPerTask times per task\n *              with actionable feedback. The budget is shared by both modes and\n *              by every gated tool.\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 preference dimension scoring below this fails. */\n  threshold: z.number().min(0).max(1).default(0.5),\n  /** The `plain` dimension, judged on every message. Independent of `mode`. */\n  plainMode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  /**\n   * `plain` scoring below this fails. Jev scores dense status text low and\n   * plain text high with little in between, so this sits far below `threshold`.\n   */\n  plainThreshold: z.number().min(0).max(1).default(0.25),\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/** MCP tools that post agent-authored text to Slack, all with a `message` arg. */\nexport const SLACK_TOOLS = new Set([\n  \"slack-reply\",\n  \"slack-post\",\n  \"slack-start-thread\",\n  \"slack-update\",\n]);\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/**\n * The `plain` rubric, from the `comms` skill (Simpler and Precise modes). Jev\n * separates dense from plain text reliably only with contrasting examples; a\n * prose-only rubric scored a plain rewrite as low as the dense original.\n */\nexport const PLAIN_RULES = [\n  \"Examples of NOT plain: 'p50 Δ +120ms vs baseline (n=37)', 'error rate 2.1% → 0.4% (cohort B, ±0.3 at 95%)', 'cost $-42/day', 'first-call hit ratio 0.61', 'drift unmeasured; 2 flaky'.\",\n  \"Examples of plain: 'Pages load 120 ms slower than last week, across 37 runs', 'Errors dropped from 2 in 100 requests to 4 in 1,000', 'We spend $42 a day less', 'PR #123 keeps the migration reversible', 'Lead saves about $75 a week'.\",\n  \"Code identifiers, task ids, PR numbers, links, file paths and version numbers are fine as they are.\",\n];\n\nexport const PLAIN_QUESTION = {\n  type: \"noul\",\n  instructions:\n    \"Is agent_message written like the plain examples in plain_language_rules rather than like the NOT plain ones? Ignore length and tone.\",\n  criteria: {\n    true: \"Written like the plain examples: everyday words and numbers with units and direction.\",\n    false:\n      \"Written like the NOT plain examples: statistics shorthand, abbreviations, signed or cryptic numbers.\",\n  },\n};\n\n/** Structured output (an outputSchema answer) is for machines; `plain` skips it. */\nexport const looksLikeJson = (text: string): boolean => {\n  if (!/^[[{]/.test(text)) return false;\n  try {\n    JSON.parse(text);\n    return true;\n  } catch {\n    return false;\n  }\n};\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// A real dense monitor post a requester had to ask to have rewritten, and that rewrite.\nconst SELFTEST_PLAIN_BAD =\n  \"Prompt cache monitor, day 7 verdict for v2.0.0: partial. Lead first-call read median 12.4k (baseline v1.173.0, n 410) → 19.1k tokens (n 2234; expected 25.0k-40.0k). First-call saving about $75/week on Lead vs v1.173.0 (expected $129; sampling noise ±$24 at 95%, one baseline version, day-to-day drift not measured); session $ change $-167/week; fleet first-call saving $-7/week.\";\nconst SELFTEST_PLAIN_GOOD =\n  \"Cheaper, but half what we hoped: Lead saves about $75 a week, not $129. Whole Lead tasks still cost $167 a week more, probably from other releases and heavier work, not this change.\";\n\nconst below = (bad: unknown, good: unknown, threshold: number): boolean =>\n  typeof bad === \"number\" && typeof good === \"number\" && bad < threshold && good >= threshold;\n\n/**\n * Run the judge on known-bad (positive control, must score below threshold) and\n * known-good (negative control, must score at or above it) messages and record\n * them under `selftest:last`: one pair for verbosity, one for `plain`. Proves key,\n * egress and KV from inside the API runtime 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 judge = (message: string, dim: \"verbosity\" | \"plain\") =>\n      askJev(\n        dim === \"plain\"\n          ? { plain_language_rules: PLAIN_RULES, agent_message: message }\n          : { requester_preferences: SELFTEST_PREFS, agent_message: message },\n        { [dim]: dim === \"plain\" ? PLAIN_QUESTION : buildQuestions(SELFTEST_PREFS).verbosity },\n        transport,\n        cfg,\n        signal,\n      ).then((r) => r.scores[dim] ?? null);\n    const [bad, good, plainBad, plainGood] = await Promise.all([\n      judge(SELFTEST_BAD, \"verbosity\"),\n      judge(SELFTEST_GOOD, \"verbosity\"),\n      judge(SELFTEST_PLAIN_BAD, \"plain\"),\n      judge(SELFTEST_PLAIN_GOOD, \"plain\"),\n    ]);\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: below(bad, good, cfg.threshold),\n        plainThreshold: cfg.plainThreshold,\n        plainPositiveControlBadScore: plainBad,\n        plainNegativeControlGoodScore: plainGood,\n        plainControlsOk: below(plainBad, plainGood, cfg.plainThreshold),\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,\n       t.creatorAgentId\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/** Slack user mentions in agent text: `<@U123>` or `<@U123|name>`. */\nconst MENTION_RE = /<@([UW][A-Z0-9]+)(?:\\|[^>]*)?>/g;\nconst MAX_MENTIONS = 5;\n\n/** Mentioned Slack user ids in order of first appearance, capped. */\nexport const mentionedSlackIds = (text: string): string[] => {\n  const ids: string[] = [];\n  for (const m of text.matchAll(MENTION_RE)) {\n    if (!ids.includes(m[1]!)) ids.push(m[1]!);\n    if (ids.length >= MAX_MENTIONS) break;\n  }\n  return ids;\n};\n\nconst addresseeSql = (n: number) => `SELECT x.externalId, u.id, u.name,\n       json_extract(u.metadata, '$.comms') AS comms\nFROM user_external_ids x\nJOIN users u ON u.id = x.userId\nWHERE x.kind = 'slack' AND x.externalId IN (${Array(n).fill(\"?\").join(\", \")})`;\n\nconst parsePrefs = (raw: unknown): Prefs | null => {\n  if (!raw) return null;\n  const parsed = typeof raw === \"string\" ? JSON.parse(raw) : raw;\n  return parsed && typeof parsed === \"object\" && Object.keys(parsed).length > 0\n    ? (parsed as Prefs)\n    : null;\n};\n\ntype Audience = { id: string; name: string; prefs: Prefs; via: \"mention\" | \"requester\" };\n\n/**\n * Whose preferences a message is judged against. In a thread with several\n * people, the message is for whoever it @-mentions: the first mentioned person\n * with stored preferences wins, including the requester only if they have prefs.\n * Without such a mention, the task requester (the\n * person whose message created this task). One SQL read, only when the text\n * mentions someone; no judge call.\n */\nconst resolveAudience = async (\n  swarm: Swarm,\n  text: string,\n  requester: Audience,\n): Promise<Audience> => {\n  const ids = mentionedSlackIds(text);\n  if (ids.length === 0) return requester;\n  const q = (await swarm.db_query({ sql: addresseeSql(ids.length), params: ids })) as Envelope;\n  const rows = q?.data?.rows ?? q?.rows ?? [];\n  for (const slackId of ids) {\n    const row = rows.find((r) => String(cell(r, 0, \"externalId\")) === slackId);\n    if (!row) continue;\n    const userId = String(cell(row, 1, \"id\") ?? \"\");\n    // A requester with stored preferences keeps their own task context.\n    if (userId && userId === requester.id) {\n      if (Object.keys(requester.prefs).length > 0) return requester;\n      continue;\n    }\n    const prefs = parsePrefs(cell(row, 3, \"comms\"));\n    if (!prefs) continue;\n    return { id: userId, name: String(cell(row, 2, \"name\") ?? userId), prefs, via: \"mention\" };\n  }\n  return requester;\n};\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\n/** The text a gated call would put in front of a human, and the task it belongs to. */\nconst gatedText = (\n  tool: string,\n  args: Record<string, unknown>,\n  sourceTaskId: string | undefined,\n): { text: string; taskId: string } | null => {\n  if (tool === \"store-progress\") {\n    if (args.status !== \"completed\") return null;\n    return {\n      text: typeof args.output === \"string\" ? args.output.trim() : \"\",\n      taskId: String(args.taskId ?? sourceTaskId ?? \"\"),\n    };\n  }\n  if (SLACK_TOOLS.has(tool)) {\n    // slack-reply names its task; the other tools post from the caller's task context.\n    const named = tool === \"slack-reply\" ? args.taskId : undefined;\n    return {\n      text: typeof args.message === \"string\" ? args.message.trim() : \"\",\n      taskId: String(named ?? sourceTaskId ?? \"\"),\n    };\n  }\n  return null;\n};\n\nconst extension: SwarmExtension = (api) => {\n  api.on(\"pre.tool.call\", async (event, ctx) => {\n    if (event.tool !== \"store-progress\" && !SLACK_TOOLS.has(event.tool)) return;\n    const origin = event.requestInfo?.callOrigin;\n    if (origin === \"extension\") return;\n\n    const cfg = cfgOf(ctx.config);\n    if (cfg.mode === \"off\" && cfg.plainMode === \"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 (\n      event.tool === \"store-progress\" &&\n      args.status !== \"completed\" &&\n      typeof args.progress === \"string\" &&\n      args.progress.startsWith(SELFTEST)\n    ) {\n      await selfTest(ctx.swarm, cfg, ctx.signal);\n      return;\n    }\n\n    const gated = gatedText(event.tool, args, event.requestInfo?.sourceTaskId);\n    if (!gated?.text) return;\n    const { text, taskId } = gated;\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 || \"the requester\"));\n      const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n      const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n      // Judge only a call the tool itself will accept, so no agent can ship another\n      // task's thread and preferences to the external judge. store-progress follows\n      // its write rule; the Slack tools follow slack-reply's: the caller is the\n      // task's assignee or its creator.\n      const callerId = event.requestInfo?.agentId;\n      const creatorAgentId = String(cell(row, 8, \"creatorAgentId\") ?? \"\");\n      const allowed =\n        event.tool === \"store-progress\"\n          ? await mayWriteProgress(ctx.swarm, callerId, agentId)\n          : Boolean(callerId) && (callerId === agentId || callerId === creatorAgentId);\n      if (!allowed) return;\n\n      // A completion reaches a human only on a Slack task; a Slack tool always does.\n      if (event.tool === \"store-progress\" && source !== \"slack\" && !slackThreadTs) return;\n\n      const requester: Audience = {\n        id: requesterId,\n        name: requesterName,\n        prefs: parsePrefs(commsRaw) ?? {},\n        via: \"requester\",\n      };\n      // `plain` alone judges no one's preferences, so it skips the lookup.\n      const audience =\n        cfg.mode === \"off\" ? requester : await resolveAudience(ctx.swarm, text, requester);\n      const { prefs, name: audienceName } = audience;\n\n      const questions: Record<string, unknown> = cfg.mode === \"off\" ? {} : buildQuestions(prefs);\n      // Only a store-progress outputSchema answer is machine JSON; a Slack post is\n      // always read by a human, JSON or not.\n      if (cfg.plainMode !== \"off\" && (event.tool !== \"store-progress\" || !looksLikeJson(text)))\n        questions.plain = PLAIN_QUESTION;\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 message to the human who requested the work.\",\n          requester: audienceName,\n          requester_preferences: prefs,\n          latest_request: ask,\n          thread_opening: threadOpening,\n          judging_rules: JUDGING_RULES,\n          plain_language_rules: PLAIN_RULES,\n          agent_message: text,\n        },\n        questions,\n        transport,\n        cfg,\n        ctx.signal,\n      );\n\n      const limitOf = (dim: string) => (dim === \"plain\" ? cfg.plainThreshold : cfg.threshold);\n      const failed = Object.entries(scores)\n        .filter(([k, v]) => v < limitOf(k))\n        .map(([k]) => k);\n      // Script SDK calls never reach pre.tool.call today; if one does, record it only.\n      const blocking =\n        origin === \"script-sdk\"\n          ? []\n          : failed.filter((d) => (d === \"plain\" ? cfg.plainMode : cfg.mode) === \"enforce\");\n\n      const verdict = {\n        at: new Date().toISOString(),\n        tool: event.tool,\n        taskId,\n        agentId,\n        source,\n        requester: requesterName,\n        requesterId,\n        judgedFor: audience.via,\n        audienceId: audience.id,\n        audience: audienceName,\n        provider: transport.provider,\n        scores,\n        failed,\n        threshold: cfg.threshold,\n        plainThreshold: cfg.plainThreshold,\n        mode: cfg.mode,\n        plainMode: cfg.plainMode,\n        latencyMs,\n        preferences: prefs,\n        askPreview: ask.slice(0, 400),\n        outputPreview: text.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 = blocking.length > 0 && 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: blocking.length > 0 ? \"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 lines = [\n        blocking.includes(\"plain\")\n          ? `Comms gate: this message is not in plain words for ${audienceName}.`\n          : `Comms gate: this output does not match ${audienceName}'s stated preferences.`,\n      ];\n      for (const d of blocking) {\n        const score = `${d} (${scores[d]!.toFixed(2)} vs ${limitOf(d)})`;\n        lines.push(\n          d === \"plain\"\n            ? `${score}: a reader outside the swarm cannot follow it on first read.`\n            : `${score}: requested ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n        );\n      }\n      lines.push(\n        blocking.includes(\"plain\")\n          ? `Rewrite the message with the \\`comms\\` skill (Simpler mode): common words, one idea per sentence, every number with a unit and a direction word, shorthand explained or replaced. Keep every number, name, link and hedge verbatim, then call ${event.tool} again.`\n          : `Rewrite the message to match and call ${event.tool} again. Do not change the facts, only how they are said.`,\n      );\n      return block(lines.join(\"\\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: {\n            at: new Date().toISOString(),\n            tool: event.tool,\n            taskId,\n            error: String(err).slice(0, 400),\n          },\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"
+    "readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads, and post to Slack threads directly. This extension judges that text with Jev, [TypeSafe](https://typesafe.ai)'s decision model: against the requester's stated comms preferences and their latest request, and against a plain-language rubric that applies to every message. In `enforce` it blocks a failing call once and tells the agent what to fix. A `plain` failure points the agent at the `comms` skill.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\", \"plainMode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.\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 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`mode` governs the preference dimensions (`verbosity`, `tone`, `language`). `plainMode` governs `plain`. A dimension blocks only when its own mode is `enforce`. Both share one block budget per task, across every gated tool.\n\n## What it gates\n\nHook: `pre.tool.call` on:\n\n- `store-progress` with `status: \"completed\"` and a non-empty `output`, on a task that came from Slack (`source = \"slack\"` or a `slackThreadTs`). Other completions pass without a Jev call.\n- `slack-reply`, `slack-post`, `slack-start-thread` and `slack-update`, judged on `message`. The task is `slack-reply`'s `taskId`, else the caller's task context. A post with no task context passes.\n\nOnly a call the tool itself accepts is judged, so no other task's text reaches Jev. For `store-progress` the caller must own the task, the task must be unassigned, or the caller must be a lead. For the Slack tools the caller must be the task's assignee or its creator, the rule `slack-reply` enforces. Calls made by extensions are skipped. Script SDK calls never reach `pre.tool.call` (the tool registrar dispatches it only for MCP calls); if one ever does, the gate records it and never blocks.\n\nA requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.\n\nIn a thread with several people, the requester is the person whose message created the task. A message that @-mentions someone (`<@U123>`) is judged against the first mentioned person with stored preferences, resolved through their Slack identity in `user_external_ids`; otherwise against the requester. The lookup is one SQL read, only when the text mentions someone and `mode` is not `off`. The verdict records who was judged in `judgedFor` (`mention` or `requester`) and `audience`.\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\nIt also asks `plain` on every message unless `plainMode` is `off` or the text is a JSON document (structured output for an `outputSchema`). The rubric comes from the `comms` skill: everyday words, one idea per sentence, every number with a unit and a direction word, and no unexplained shorthand (n, median, p90, cohort, baseline, delta, `±X at 95%`). Code identifiers, task ids, PR numbers, links and versions are fine. Jev gets contrasting plain and dense examples in `plain_language_rules`; a prose-only rubric scored plain rewrites as low as the dense originals.\n\nAll questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.\n\n### Calibration of `plain`\n\nJev scores dense status text near 0 and plain text near 0.8 to 0.9, with a wide middle of compact but readable engineering notes. Measured on 400 Slack-facing completions over 7 days, at `threshold` 0.75 for preferences:\n\n| `plainThreshold` | Newly blocked (of messages that pass today) |\n|---|---|\n| 0.75 | 81% to 83% |\n| 0.3 | 9% to 13% |\n| 0.25 (default) | 5% to 7% |\n\nAt 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.\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 a dense and a plain message on `plain`, then writes `selftest:last`: every score, both thresholds, the provider, `controlsOk` (verbosity: bad below `threshold`, good at or above it) and `plainControlsOk` (the same against `plainThreshold`). 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 preference dimension scoring below this fails |\n| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |\n| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |\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 `tool`, `scores`, `failed`, `mode`, `plainMode`, `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` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `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 call after a block goes through once the budget is spent, even if it still fails.\n- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).\n"
   },
   "deploy-awareness": {
     "manifestFile": "manifest.json",

package/src/http/all-routes.ts

@@ -70,6 +70,7 @@ import "./trackers/linear";
 import "./ranking";
 import "./used-by";
 import "./fleet-benchmark";
+import "./user-roles";
 import "./users";
 import "./webhooks";
 import "./workflow-events";