@desplega.ai/agent-swarm 2.5.2 → 2.5.3

package/templates/extensions/comms-adherence-gate/hooks.ts

@@ -5,22 +5,30 @@ import { z } from "zod";
  * comms-adherence-gate
  *
  * When an agent calls `store-progress` with status "completed" on a task that
- * reaches a human in Slack, judge the `output` against the requesting user's
- * stored comms preferences (users.metadata.$.comms) with Jev, and against what
- * that user actually asked for in their latest message. An explicit request
- * ("tell me a long joke", "explain in detail") outranks the stored default, so
- * a requested long answer is not a verbosity failure.
+ * reaches a human in Slack, or posts to Slack itself (`slack-reply`,
+ * `slack-post`, `slack-start-thread`, `slack-update`), judge the text with Jev:
+ * against the requesting user's stored comms preferences
+ * (users.metadata.$.comms) and what that user actually asked for in their
+ * latest message, and against a plain-language rubric that applies to every
+ * message whatever preferences exist. An explicit request ("tell me a long
+ * joke", "explain in detail") outranks the stored default, so a requested long
+ * answer is not a verbosity failure.
+ *
+ * Threads with several people: a message that @-mentions someone is judged
+ * against the first mentioned person with stored preferences, skipping a
+ * requester without preferences; otherwise against the requester. `plain` applies to everyone.
  *
  * Transport (config.provider): Jev is served by TypeSafe directly and by
  * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}
  * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when
  * set, else OPENROUTER_API_KEY.
  *
- * modes (config.mode):
+ * modes (config.mode for the preference dimensions, config.plainMode for `plain`):
  *   off     -> never evaluate
  *   shadow  -> evaluate + record, never block (default)
- *   enforce -> record, and block the completion up to maxBlocksPerTask times
- *              per task with actionable feedback
+ *   enforce -> record, and block the call up to maxBlocksPerTask times per task
+ *              with actionable feedback. The budget is shared by both modes and
+ *              by every gated tool.
  *
  * Fails OPEN on every error: a judge outage must never wall the swarm.
  * Every verdict lands in KV namespace `ext:comms-gate`.
@@ -28,8 +36,15 @@ import { z } from "zod";
 
 export const config = z.object({
   mode: z.enum(["off", "shadow", "enforce"]).default("shadow"),
-  /** A dimension scoring below this fails. */
+  /** A preference dimension scoring below this fails. */
   threshold: z.number().min(0).max(1).default(0.5),
+  /** The `plain` dimension, judged on every message. Independent of `mode`. */
+  plainMode: z.enum(["off", "shadow", "enforce"]).default("shadow"),
+  /**
+   * `plain` scoring below this fails. Jev scores dense status text low and
+   * plain text high with little in between, so this sits far below `threshold`.
+   */
+  plainThreshold: z.number().min(0).max(1).default(0.25),
   timeoutMs: z.number().int().positive().default(4000),
   maxBlocksPerTask: z.number().int().min(0).default(1),
   provider: z.enum(["auto", "typesafe", "openrouter"]).default("auto"),
@@ -48,6 +63,13 @@ const NS = "ext:comms-gate";
 const TYPESAFE_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
 const OPENROUTER_ENDPOINT = "https://openrouter.ai/api/alpha/decisions";
 const UUID_RE = /^[0-9a-fA-F-]{36}$/;
+/** MCP tools that post agent-authored text to Slack, all with a `message` arg. */
+export const SLACK_TOOLS = new Set([
+  "slack-reply",
+  "slack-post",
+  "slack-start-thread",
+  "slack-update",
+]);
 // The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.
 const MAX_TIMEOUT_MS = 4000;
 
@@ -96,6 +118,39 @@ const JUDGING_RULES = [
 
 type Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;
 
+/**
+ * The `plain` rubric, from the `comms` skill (Simpler and Precise modes). Jev
+ * separates dense from plain text reliably only with contrasting examples; a
+ * prose-only rubric scored a plain rewrite as low as the dense original.
+ */
+export const PLAIN_RULES = [
+  "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'.",
+  "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'.",
+  "Code identifiers, task ids, PR numbers, links, file paths and version numbers are fine as they are.",
+];
+
+export const PLAIN_QUESTION = {
+  type: "noul",
+  instructions:
+    "Is agent_message written like the plain examples in plain_language_rules rather than like the NOT plain ones? Ignore length and tone.",
+  criteria: {
+    true: "Written like the plain examples: everyday words and numbers with units and direction.",
+    false:
+      "Written like the NOT plain examples: statistics shorthand, abbreviations, signed or cryptic numbers.",
+  },
+};
+
+/** Structured output (an outputSchema answer) is for machines; `plain` skips it. */
+export const looksLikeJson = (text: string): boolean => {
+  if (!/^[[{]/.test(text)) return false;
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 /** One `noul` question per stated preference the gate knows how to judge. */
 export const buildQuestions = (prefs: Prefs): Record<string, unknown> => {
   const questions: Record<string, unknown> = {};
@@ -246,27 +301,41 @@ const SELFTEST_BAD =
   "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!";
 const SELFTEST_GOOD =
   "Went with option B: it is the only one that keeps the migration reversible. PR #123.";
+// A real dense monitor post a requester had to ask to have rewritten, and that rewrite.
+const SELFTEST_PLAIN_BAD =
+  "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.";
+const SELFTEST_PLAIN_GOOD =
+  "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.";
+
+const below = (bad: unknown, good: unknown, threshold: number): boolean =>
+  typeof bad === "number" && typeof good === "number" && bad < threshold && good >= threshold;
 
 /**
- * Run the judge on a known-bad (positive control, must score below threshold) and a
- * known-good (negative control, must score at or above it) message and record both
- * under `selftest:last`. Proves key, egress and KV from inside the API runtime
- * without touching real traffic.
+ * Run the judge on known-bad (positive control, must score below threshold) and
+ * known-good (negative control, must score at or above it) messages and record
+ * them under `selftest:last`: one pair for verbosity, one for `plain`. Proves key,
+ * egress and KV from inside the API runtime without touching real traffic.
  */
 const selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {
   const started = Date.now();
   try {
     const transport = resolveTransport(cfg);
-    const questions = { verbosity: buildQuestions(SELFTEST_PREFS).verbosity };
-    const judge = (message: string) =>
+    const judge = (message: string, dim: "verbosity" | "plain") =>
       askJev(
-        { requester_preferences: SELFTEST_PREFS, agent_message: message },
-        questions,
+        dim === "plain"
+          ? { plain_language_rules: PLAIN_RULES, agent_message: message }
+          : { requester_preferences: SELFTEST_PREFS, agent_message: message },
+        { [dim]: dim === "plain" ? PLAIN_QUESTION : buildQuestions(SELFTEST_PREFS).verbosity },
         transport,
         cfg,
         signal,
-      ).then((r) => r.scores.verbosity ?? null);
-    const [bad, good] = await Promise.all([judge(SELFTEST_BAD), judge(SELFTEST_GOOD)]);
+      ).then((r) => r.scores[dim] ?? null);
+    const [bad, good, plainBad, plainGood] = await Promise.all([
+      judge(SELFTEST_BAD, "verbosity"),
+      judge(SELFTEST_GOOD, "verbosity"),
+      judge(SELFTEST_PLAIN_BAD, "plain"),
+      judge(SELFTEST_PLAIN_GOOD, "plain"),
+    ]);
     await swarm.kv_set({
       namespace: NS,
       key: "selftest:last",
@@ -276,11 +345,11 @@ const selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<v
         threshold: cfg.threshold,
         positiveControlBadScore: bad,
         negativeControlGoodScore: good,
-        controlsOk:
-          typeof bad === "number" &&
-          typeof good === "number" &&
-          bad < cfg.threshold &&
-          good >= cfg.threshold,
+        controlsOk: below(bad, good, cfg.threshold),
+        plainThreshold: cfg.plainThreshold,
+        plainPositiveControlBadScore: plainBad,
+        plainNegativeControlGoodScore: plainGood,
+        plainControlsOk: below(plainBad, plainGood, cfg.plainThreshold),
         latencyMs: Date.now() - started,
       },
     });
@@ -302,13 +371,77 @@ const selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<v
 const TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,
        json_extract(u.metadata, '$.comms') AS comms, u.name,
        substr(t.task, 1, 400) AS askHead,
-       substr(t.task, -1400) AS askTail
+       substr(t.task, -1400) AS askTail,
+       t.creatorAgentId
 FROM agent_tasks t
 LEFT JOIN users u ON u.id = t.requestedByUserId
 WHERE t.id = ?`;
 
 const LEAD_SQL = "SELECT isLead FROM agents WHERE id = ?";
 
+/** Slack user mentions in agent text: `<@U123>` or `<@U123|name>`. */
+const MENTION_RE = /<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g;
+const MAX_MENTIONS = 5;
+
+/** Mentioned Slack user ids in order of first appearance, capped. */
+export const mentionedSlackIds = (text: string): string[] => {
+  const ids: string[] = [];
+  for (const m of text.matchAll(MENTION_RE)) {
+    if (!ids.includes(m[1]!)) ids.push(m[1]!);
+    if (ids.length >= MAX_MENTIONS) break;
+  }
+  return ids;
+};
+
+const addresseeSql = (n: number) => `SELECT x.externalId, u.id, u.name,
+       json_extract(u.metadata, '$.comms') AS comms
+FROM user_external_ids x
+JOIN users u ON u.id = x.userId
+WHERE x.kind = 'slack' AND x.externalId IN (${Array(n).fill("?").join(", ")})`;
+
+const parsePrefs = (raw: unknown): Prefs | null => {
+  if (!raw) return null;
+  const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  return parsed && typeof parsed === "object" && Object.keys(parsed).length > 0
+    ? (parsed as Prefs)
+    : null;
+};
+
+type Audience = { id: string; name: string; prefs: Prefs; via: "mention" | "requester" };
+
+/**
+ * Whose preferences a message is judged against. In a thread with several
+ * people, the message is for whoever it @-mentions: the first mentioned person
+ * with stored preferences wins, including the requester only if they have prefs.
+ * Without such a mention, the task requester (the
+ * person whose message created this task). One SQL read, only when the text
+ * mentions someone; no judge call.
+ */
+const resolveAudience = async (
+  swarm: Swarm,
+  text: string,
+  requester: Audience,
+): Promise<Audience> => {
+  const ids = mentionedSlackIds(text);
+  if (ids.length === 0) return requester;
+  const q = (await swarm.db_query({ sql: addresseeSql(ids.length), params: ids })) as Envelope;
+  const rows = q?.data?.rows ?? q?.rows ?? [];
+  for (const slackId of ids) {
+    const row = rows.find((r) => String(cell(r, 0, "externalId")) === slackId);
+    if (!row) continue;
+    const userId = String(cell(row, 1, "id") ?? "");
+    // A requester with stored preferences keeps their own task context.
+    if (userId && userId === requester.id) {
+      if (Object.keys(requester.prefs).length > 0) return requester;
+      continue;
+    }
+    const prefs = parsePrefs(cell(row, 3, "comms"));
+    if (!prefs) continue;
+    return { id: userId, name: String(cell(row, 2, "name") ?? userId), prefs, via: "mention" };
+  }
+  return requester;
+};
+
 /**
  * Mirrors the `task.progress.write` rule store-progress enforces
  * (src/rbac/legacy-policy.ts): the caller owns the task, the task is
@@ -327,29 +460,56 @@ const mayWriteProgress = async (
   return Number(cell(row, 0, "isLead") ?? 0) === 1;
 };
 
+/** The text a gated call would put in front of a human, and the task it belongs to. */
+const gatedText = (
+  tool: string,
+  args: Record<string, unknown>,
+  sourceTaskId: string | undefined,
+): { text: string; taskId: string } | null => {
+  if (tool === "store-progress") {
+    if (args.status !== "completed") return null;
+    return {
+      text: typeof args.output === "string" ? args.output.trim() : "",
+      taskId: String(args.taskId ?? sourceTaskId ?? ""),
+    };
+  }
+  if (SLACK_TOOLS.has(tool)) {
+    // slack-reply names its task; the other tools post from the caller's task context.
+    const named = tool === "slack-reply" ? args.taskId : undefined;
+    return {
+      text: typeof args.message === "string" ? args.message.trim() : "",
+      taskId: String(named ?? sourceTaskId ?? ""),
+    };
+  }
+  return null;
+};
+
 const extension: SwarmExtension = (api) => {
   api.on("pre.tool.call", async (event, ctx) => {
-    if (event.tool !== "store-progress") return;
-    if (event.requestInfo?.callOrigin === "extension") return;
+    if (event.tool !== "store-progress" && !SLACK_TOOLS.has(event.tool)) return;
+    const origin = event.requestInfo?.callOrigin;
+    if (origin === "extension") return;
 
     const cfg = cfgOf(ctx.config);
-    if (cfg.mode === "off") return;
+    if (cfg.mode === "off" && cfg.plainMode === "off") return;
 
     const args = (event.args ?? {}) as Record<string, unknown>;
 
     // Self-test hatch: a progress call whose text starts with the sentinel runs
     // the controls and records them under `selftest:last`.
-    if (args.status !== "completed") {
-      if (typeof args.progress === "string" && args.progress.startsWith(SELFTEST)) {
-        await selfTest(ctx.swarm, cfg, ctx.signal);
-      }
+    if (
+      event.tool === "store-progress" &&
+      args.status !== "completed" &&
+      typeof args.progress === "string" &&
+      args.progress.startsWith(SELFTEST)
+    ) {
+      await selfTest(ctx.swarm, cfg, ctx.signal);
       return;
     }
 
-    const output = typeof args.output === "string" ? args.output.trim() : "";
-    if (!output) return;
-
-    const taskId = String(args.taskId ?? event.requestInfo?.sourceTaskId ?? "");
+    const gated = gatedText(event.tool, args, event.requestInfo?.sourceTaskId);
+    if (!gated?.text) return;
+    const { text, taskId } = gated;
     if (!UUID_RE.test(taskId)) return;
 
     try {
@@ -362,33 +522,54 @@ const extension: SwarmExtension = (api) => {
       const agentId = String(cell(row, 2, "agentId") ?? "");
       const requesterId = String(cell(row, 3, "requestedByUserId") ?? "");
       const commsRaw = cell(row, 4, "comms");
-      const requesterName = String(cell(row, 5, "name") ?? requesterId);
+      const requesterName = String(cell(row, 5, "name") ?? (requesterId || "the requester"));
       const threadOpening = String(cell(row, 6, "askHead") ?? "");
       const ask = latestAsk(String(cell(row, 7, "askTail") ?? ""));
 
-      // Judge only a completion store-progress will accept, so no agent can ship
-      // another task's thread and preferences to the external judge.
-      if (!(await mayWriteProgress(ctx.swarm, event.requestInfo?.agentId, agentId))) return;
-
-      // Only where the text actually reaches a human in Slack.
-      if (source !== "slack" && !slackThreadTs) return;
-      if (!commsRaw) return; // no stated preferences -> nothing to judge against
-      const prefs = (typeof commsRaw === "string" ? JSON.parse(commsRaw) : commsRaw) as Prefs;
-      if (!prefs || typeof prefs !== "object") return;
-
-      const questions = buildQuestions(prefs);
+      // Judge only a call the tool itself will accept, so no agent can ship another
+      // task's thread and preferences to the external judge. store-progress follows
+      // its write rule; the Slack tools follow slack-reply's: the caller is the
+      // task's assignee or its creator.
+      const callerId = event.requestInfo?.agentId;
+      const creatorAgentId = String(cell(row, 8, "creatorAgentId") ?? "");
+      const allowed =
+        event.tool === "store-progress"
+          ? await mayWriteProgress(ctx.swarm, callerId, agentId)
+          : Boolean(callerId) && (callerId === agentId || callerId === creatorAgentId);
+      if (!allowed) return;
+
+      // A completion reaches a human only on a Slack task; a Slack tool always does.
+      if (event.tool === "store-progress" && source !== "slack" && !slackThreadTs) return;
+
+      const requester: Audience = {
+        id: requesterId,
+        name: requesterName,
+        prefs: parsePrefs(commsRaw) ?? {},
+        via: "requester",
+      };
+      // `plain` alone judges no one's preferences, so it skips the lookup.
+      const audience =
+        cfg.mode === "off" ? requester : await resolveAudience(ctx.swarm, text, requester);
+      const { prefs, name: audienceName } = audience;
+
+      const questions: Record<string, unknown> = cfg.mode === "off" ? {} : buildQuestions(prefs);
+      // Only a store-progress outputSchema answer is machine JSON; a Slack post is
+      // always read by a human, JSON or not.
+      if (cfg.plainMode !== "off" && (event.tool !== "store-progress" || !looksLikeJson(text)))
+        questions.plain = PLAIN_QUESTION;
       if (Object.keys(questions).length === 0) return;
 
       const transport = resolveTransport(cfg);
       const { scores, latencyMs } = await askJev(
         {
-          role: "You audit an AI agent's final message to the human who requested the work.",
-          requester: requesterName,
+          role: "You audit an AI agent's message to the human who requested the work.",
+          requester: audienceName,
           requester_preferences: prefs,
           latest_request: ask,
           thread_opening: threadOpening,
           judging_rules: JUDGING_RULES,
-          agent_message: output,
+          plain_language_rules: PLAIN_RULES,
+          agent_message: text,
         },
         questions,
         transport,
@@ -396,26 +577,38 @@ const extension: SwarmExtension = (api) => {
         ctx.signal,
       );
 
+      const limitOf = (dim: string) => (dim === "plain" ? cfg.plainThreshold : cfg.threshold);
       const failed = Object.entries(scores)
-        .filter(([, v]) => v < cfg.threshold)
+        .filter(([k, v]) => v < limitOf(k))
         .map(([k]) => k);
+      // Script SDK calls never reach pre.tool.call today; if one does, record it only.
+      const blocking =
+        origin === "script-sdk"
+          ? []
+          : failed.filter((d) => (d === "plain" ? cfg.plainMode : cfg.mode) === "enforce");
 
       const verdict = {
         at: new Date().toISOString(),
+        tool: event.tool,
         taskId,
         agentId,
         source,
         requester: requesterName,
         requesterId,
+        judgedFor: audience.via,
+        audienceId: audience.id,
+        audience: audienceName,
         provider: transport.provider,
         scores,
         failed,
         threshold: cfg.threshold,
+        plainThreshold: cfg.plainThreshold,
         mode: cfg.mode,
+        plainMode: cfg.plainMode,
         latencyMs,
         preferences: prefs,
         askPreview: ask.slice(0, 400),
-        outputPreview: output.slice(0, 700),
+        outputPreview: text.slice(0, 700),
       };
 
       await ctx.swarm.kv_incr({ namespace: NS, key: "total" });
@@ -435,7 +628,7 @@ const extension: SwarmExtension = (api) => {
       // kv_get answers {success, data:{value}}, and {success:false} when absent.
       const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;
       const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;
-      const willBlock = cfg.mode === "enforce" && priorBlocks < cfg.maxBlocksPerTask;
+      const willBlock = blocking.length > 0 && priorBlocks < cfg.maxBlocksPerTask;
 
       await ctx.swarm.kv_set({
         namespace: NS,
@@ -446,7 +639,7 @@ const extension: SwarmExtension = (api) => {
       if (!willBlock) {
         await ctx.swarm.kv_incr({
           namespace: NS,
-          key: cfg.mode === "enforce" ? "escaped" : "shadowed",
+          key: blocking.length > 0 ? "escaped" : "shadowed",
         });
         return;
       }
@@ -454,20 +647,25 @@ const extension: SwarmExtension = (api) => {
       await ctx.swarm.kv_incr({ namespace: NS, key: "blocked" });
       await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });
 
-      const detail = failed
-        .map(
-          (d) =>
-            `${d} (${scores[d]!.toFixed(2)} vs ${cfg.threshold}) — requested: ${String(prefs[d] ?? "").slice(0, 220)}`,
-        )
-        .join("\n");
-
-      return block(
-        [
-          `Comms gate: this output does not match ${requesterName}'s stated preferences.`,
-          detail,
-          "Rewrite the output to match and call store-progress again. Do not change the facts, only how they are said.",
-        ].join("\n"),
+      const lines = [
+        blocking.includes("plain")
+          ? `Comms gate: this message is not in plain words for ${audienceName}.`
+          : `Comms gate: this output does not match ${audienceName}'s stated preferences.`,
+      ];
+      for (const d of blocking) {
+        const score = `${d} (${scores[d]!.toFixed(2)} vs ${limitOf(d)})`;
+        lines.push(
+          d === "plain"
+            ? `${score}: a reader outside the swarm cannot follow it on first read.`
+            : `${score}: requested ${String(prefs[d] ?? "").slice(0, 220)}`,
+        );
+      }
+      lines.push(
+        blocking.includes("plain")
+          ? `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.`
+          : `Rewrite the message to match and call ${event.tool} again. Do not change the facts, only how they are said.`,
       );
+      return block(lines.join("\n"));
     } catch (err) {
       // Fail open, always.
       try {
@@ -475,7 +673,12 @@ const extension: SwarmExtension = (api) => {
         await ctx.swarm.kv_set({
           namespace: NS,
           key: "error:last",
-          value: { at: new Date().toISOString(), taskId, error: String(err).slice(0, 400) },
+          value: {
+            at: new Date().toISOString(),
+            tool: event.tool,
+            taskId,
+            error: String(err).slice(0, 400),
+          },
         });
       } catch {
         /* ignore */

package/templates/extensions/comms-adherence-gate/manifest.json

@@ -1,8 +1,8 @@
 {
   "$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" }
 }

package/templates/skills/turso-interaction/content.md

@@ -89,7 +89,7 @@ turso db list   # verify
 
 Do NOT use `turso auth login` — it needs a browser. Always feed the config token in.
 
-If `turso db list` returns 401, the platform JWT has expired — refresh `TURSO_API_TOKEN` in swarm config or ask the configured token owner.
+If `turso db list` returns 401, the platform JWT has expired — refresh `TURSO_API_TOKEN` in swarm config. If you cannot mint a new one, ask the token owner with a `request-human-input` question of type `config` (`config: { key: "TURSO_API_TOKEN", scope: "global" }`) and share the returned URL. They paste the new token into the dashboard card; you get back only whether it was set, never the value. Never ask for the token in chat.
 
 ## CLI database operations
 

package/templates/skills/workflow-iterate/content.md

@@ -132,7 +132,13 @@ Use these shapes as a starting point, then confirm them against the current exec
    ```
 
    A `completed` run means the key works. A `failed` run carries the reason: `<KEY> is not configured` (missing; for `laya` it can name `LAYA_URL` or `LAYA_API_KEY`, or both), or `<KEY> was rejected by <host> (HTTP 401)` (present but refused). To probe `laya`, set `"provider": "laya"` in the ping node. If `create-workflow` says `system-one-decision` is an unregistered executor type, the node is not deployed on this swarm yet: stop and say so.
-4. If the key is missing or was rejected, **do not build the node.** Ask a human for the key with `request-human-input` or in the thread. Name the exact key and where it goes: the Secrets page (Settings > Secrets), or for `LAYA_URL` a global config value (`set-config`, scope `global`). Never ask them to paste it into chat, a task, or a definition, and never write a key into a definition.
+4. If the key is missing or was rejected, **do not build the node.** Ask a human for it with a `request-human-input` question of type `config`, one question per key, and share the returned URL in the thread:
+
+   ```json
+   { "id": "typesafe_key", "type": "config", "config": { "key": "TYPESAFE_API_KEY", "scope": "global" } }
+   ```
+
+   The person enters the value on the dashboard card, which already shows whether the key is set. A secret goes straight into encrypted config. You get back `{ key, scope, scopeId, isSecret, status, updatedAt }`; non-secret results may also include `value`. A secret value is never returned. For a non-secret value such as `LAYA_URL`, set `"isSecret": false`; add `options` or `defaultValue` when you know the valid values. When `status` is `set`, rerun step 3. Never ask them to paste a key into chat, a task, or a definition, and never write a key into a definition.
 
 Afterwards, a `warnings` entry on `create-workflow` or a patch tool means the key went missing since you checked. Treat it as step 4.
 
@@ -217,6 +223,7 @@ The same rules apply to a standalone `request-human-input` call.
 
 - **Dashboard card.** `title` is plain text. Each question's `label` is its heading and renders as markdown. `description` renders as full markdown and is the only field that shows images, so put drafts, diffs, and logs there.
 - **Code.** Fence code, logs, and JSON with a language (```` ```json ````): the block keeps its lines and scrolls. Fence a prose draft with no language: it wraps. A single newline outside a fence becomes a paragraph break.
+- **Config questions.** A `config` question (`config: { key, scope }`) renders the key, whether it is already set, and a password field for secrets or a select for non-secret `options`. The value is written only when the request resolves approved, and the response holds only the result (`status` `set`, `kept`, or `skipped`), never a secret value. It needs `approvers.policy: "any"`. Use it whenever you need a person to supply a config value or secret.
 - **Images.** Put an `http(s)` URL ending in `.png`, `.jpg`, `.jpeg`, `.gif`, or `.webp` alone on its own line in `description`, or use `![alt](url)`. The link must outlive the request: an expired presigned URL shows an "image unavailable" note.
 - **Slack.** A node's `notifications` post the title, the question labels (each collapsed to one line, capped at 3000 characters in total), a Review button, and the timeout. Descriptions, options, code, and images are not shown, so the title and labels must make sense alone. `request-human-input` posts nothing to Slack: share the returned URL yourself.