@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/workflows/retry-poller.ts

@@ -61,6 +61,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
           // the run were read outside it: a cancel committing in between must
           // win, or the step re-executes inside a cancelled run.
           if (!(await claimRetry(run.id, step.id))) continue;
+          // Every result write below is fenced on this claim, so a cancel or
+          // another settle that commits while the executor runs wins.
+          const fence = { retryCount: step.retryCount };
 
           // Rebuild `run.id`, upstream outputs and the node's declared-inputs
           // context the way the original execution saw them. Without the alias
@@ -78,6 +81,8 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               step.id,
               scriptBodyInterpolationError(node.id, scriptBodyUnresolved),
               step.retryCount,
+              undefined,
+              { fence },
             );
             continue;
           }
@@ -104,14 +109,17 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
             if (result.status === "failed") {
               // Re-failed — use the EXISTING retryCount from the step.
               // checkpointStepFailure handles marking run as failed if no retries left,
-              // or setting nextRetryAt for the next poll cycle.
-              const retryPolicy = node.retry || executor.retryPolicy;
+              // or setting nextRetryAt for the next poll cycle. A non-retryable
+              // failure skips the policy, as in executeStep.
+              const retryPolicy =
+                result.retryable === false ? undefined : node.retry || executor.retryPolicy;
               await checkpointStepFailure(
                 run.id,
                 step.id,
                 result.error || "Retry failed",
                 step.retryCount,
                 retryPolicy,
+                { fence, output: result.output },
               );
             } else if (
               "async" in result &&
@@ -150,6 +158,12 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               // find the parent already advanced.
               const waiting = await checkpointStepWaiting(run.id, step.id, ctx);
               if (!waiting) continue;
+              // As in executeStep: a child run that finished before the step
+              // parked had its event dropped.
+              if ((result as AsyncExecutorResult).waitFor === "workflow.child.finished") {
+                const { resumeFromChildRun } = await import("./resume");
+                await resumeFromChildRun(step.id, registry);
+              }
             } else {
               // Success! Re-run validation if configured before checkpointing.
               let validationPassed: boolean | undefined;
@@ -168,6 +182,8 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
                     step.id,
                     "Validation failed (mustPass)",
                     step.retryCount,
+                    undefined,
+                    { fence },
                   );
                   continue;
                 }
@@ -186,6 +202,7 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
                     "Validation failed, retrying",
                     step.retryCount,
                     retryPolicy,
+                    { fence },
                   );
                   continue;
                 }
@@ -197,7 +214,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               result.nextPort = resolveValidationPort(node.next, result.nextPort, validationPassed);
 
               // Validation passed (or no validation) — checkpoint and continue
-              await checkpointStep(run.id, step.id, step.nodeId, result, ctx);
+              if (!(await checkpointStep(run.id, step.id, step.nodeId, result, ctx, { fence }))) {
+                continue;
+              }
 
               const port = result.nextPort || "default";
               const successors = getSuccessors(workflow.definition, step.nodeId, port);
@@ -219,7 +238,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
             if (await failRunOnUnreadableReplay(run.id, err, step.id)) continue;
             const errorMsg = err instanceof Error ? err.message : String(err);
             const retryPolicy = node.retry || executor.retryPolicy;
-            await checkpointStepFailure(run.id, step.id, errorMsg, step.retryCount, retryPolicy);
+            await checkpointStepFailure(run.id, step.id, errorMsg, step.retryCount, retryPolicy, {
+              fence,
+            });
           }
         } catch (err) {
           if (await failRunOnUnreadableReplay(step.runId, err, step.id)) continue;

package/templates/extensions/comms-adherence-gate/README.md

@@ -1,14 +1,14 @@
 # comms-adherence-gate
 
-Agents 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.
+Agents 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.
 
 Install config:
 
 ```json
-{ "mode": "shadow" }
+{ "mode": "shadow", "plainMode": "shadow" }
 ```
 
-Start in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`.
+Start in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.
 
 ## Modes
 
@@ -16,14 +16,22 @@ Start in `shadow`, read the verdicts in KV for a few days, then switch to `enfor
 |---|---|
 | `off` | Never evaluates. |
 | `shadow` (default) | Asks Jev and records the verdict. Never blocks. |
-| `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. |
+| `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. |
+
+`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.
 
 ## What it gates
 
-Hook: `pre.tool.call` on `store-progress` with `status: "completed"` and a non-empty `output`. Calls made by extensions are skipped. The task must:
+Hook: `pre.tool.call` on:
+
+- `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.
+- `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.
+
+Only 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.
 
-1. Come from Slack (`source = "slack"` or a `slackThreadTs`). Other tasks pass without a Jev call.
-2. Have a requester with stated preferences in `users.metadata.comms`. A requester with none passes. Set them with the `manage-user` tool.
+A requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.
+
+In 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`.
 
 ## Decision
 
@@ -31,7 +39,21 @@ The gate reads the task row and asks one `noul` question per stated preference i
 
 Jev 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.
 
-A dimension fails when its score is below `threshold`. Any failed dimension fails the output.
+It 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.
+
+All questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.
+
+### Calibration of `plain`
+
+Jev 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:
+
+| `plainThreshold` | Newly blocked (of messages that pass today) |
+|---|---|
+| 0.75 | 81% to 83% |
+| 0.3 | 9% to 13% |
+| 0.25 (default) | 5% to 7% |
+
+At 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.
 
 ## Jev transport
 
@@ -51,14 +73,16 @@ Every error lets the completion through: a missing key, an HTTP error, a network
 
 ## Self-test
 
-Call `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.
+Call `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.
 
 ## Config
 
 | Key | Default | Notes |
 |---|---|---|
 | `mode` | `shadow` | `off`, `shadow`, or `enforce` |
-| `threshold` | `0.5` | A dimension scoring below this fails |
+| `threshold` | `0.5` | A preference dimension scoring below this fails |
+| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |
+| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |
 | `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
 | `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |
 | `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |
@@ -76,13 +100,14 @@ No key is written to config, KV, logs, or a block reason.
 
 ## KV namespace `ext:comms-gate`
 
-- `last`: the latest verdict, with `scores`, `failed`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.
+- `last`: the latest verdict, with `tool`, `scores`, `failed`, `mode`, `plainMode`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.
 - `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).
 - `blocks:<taskId>`: blocks issued for that task.
 - `error:last`, `selftest:last`.
-- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (enforce, block budget spent), `shadowed`, `error`, and `dim:<dimension>`.
+- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `error`, and `dim:<dimension>`.
 
 ## Known limits
 
 - 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.
-- 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.
+- 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.
+- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).