@desplega.ai/agent-swarm 2.0.0 → 2.1.0

package/src/workflows/executors/system-one-decision.ts

@@ -936,15 +936,29 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
       }
     }
 
+    const decided = await this.decide(config);
+    if (!decided.ok) return { status: "failed", error: decided.error };
+    if (!config.humanReview) return { status: "success", output: decided.output };
+    return this.reviewDecision(config, config.humanReview, decided.output, context, meta);
+  }
+
+  /**
+   * One decision from the provider, without the review band: resolve the target,
+   * send, validate. The credential stays in this process; the `system-one-decide`
+   * tool calls this so scripts get Jev answers without holding a key.
+   */
+  async decide(
+    config: SystemOneDecisionConfig,
+  ): Promise<{ ok: true; output: SystemOneDecisionOutput } | { ok: false; error: string }> {
     const providerId = config.provider;
     const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[providerId];
 
     // A provider with no default sends no `model` when the node sets none.
     const model = config.model ?? provider.defaultModel;
     const modelProblem = systemOneModelProblem(providerId, model);
-    if (modelProblem) return { status: "failed", error: modelProblem };
+    if (modelProblem) return { ok: false, error: modelProblem };
     const target = await this.resolveTarget(providerId, model);
-    if (!target.ok) return { status: "failed", error: target.error };
+    if (!target.ok) return { ok: false, error: target.error };
     const { apiKey, endpoint } = target;
 
     const wire = provider.wire ?? SYSTEM_ONE_WIRE;
@@ -959,13 +973,13 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
       config.timeoutMs,
       config.maxRetries,
     );
-    if (!sent.ok) return { status: "failed", error: scrub(sent.error) };
+    if (!sent.ok) return { ok: false, error: scrub(sent.error) };
 
     let parsed: unknown;
     try {
       parsed = JSON.parse(sent.text);
     } catch {
-      return { status: "failed", error: "SystemOne response was not valid JSON" };
+      return { ok: false, error: "SystemOne response was not valid JSON" };
     }
     let decision: SystemOneDecisionOutput;
     try {
@@ -978,18 +992,14 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     } catch (err) {
       if (err instanceof SystemOneWireError) {
         const withId = sent.requestId ? `${err.message} [request ${sent.requestId}]` : err.message;
-        return { status: "failed", error: scrub(withId) };
+        return { ok: false, error: scrub(withId) };
       }
       if (err instanceof SystemOneContractError) {
-        return {
-          status: "failed",
-          error: scrub(`SystemOne response failed validation: ${err.message}`),
-        };
+        return { ok: false, error: scrub(`SystemOne response failed validation: ${err.message}`) };
       }
       throw err;
     }
-    if (!config.humanReview) return { status: "success", output: decision };
-    return this.reviewDecision(config, config.humanReview, decision, context, meta);
+    return { ok: true, output: decision };
   }
 
   /**

package/src/workflows/executors/workflow-llm.ts

@@ -1,3 +1,5 @@
+import { providerBaseUrl, providerForModel, providerKeyVars } from "@desplega/model-catalog";
+import { selectCredential } from "../../utils/credentials";
 import { DEFAULT_MODEL, resolveCredential } from "../../utils/internal-ai/credentials";
 import {
   getOpenRouterAttributionHeaders,
@@ -25,6 +27,26 @@ export async function resolveWorkflowLlmConfig(
   env: NodeJS.ProcessEnv = process.env,
   options: { requireKind?: "openrouter" | "openai" } = {},
 ): Promise<WorkflowLlmConfig> {
+  // `nan/<model>`, `helmcode/<model>`, ...: an OpenAI-compatible registry
+  // provider is reached with its own key and base URL, never through OpenRouter.
+  const registryProvider = options.requireKind ? undefined : providerForModel(requestedModel);
+  if (registryProvider && requestedModel) {
+    const keyVar = providerKeyVars(registryProvider).find((name) => env[name]?.trim());
+    if (!keyVar) {
+      throw new Error(
+        `No ${registryProvider.displayName} credential found for ${requestedModel}. Set ${registryProvider.envVar}.`,
+      );
+    }
+    return {
+      // The API hydrates global config verbatim, so a key may still be a
+      // comma pool; workflow calls skip the runner's per-task pick.
+      apiKey: selectCredential(env[keyVar] as string, undefined, keyVar).selected,
+      baseURL: providerBaseUrl(registryProvider, env),
+      headers: {},
+      model: requestedModel.slice(registryProvider.id.length + 1),
+    };
+  }
+
   const credential = await resolveCredential({ env });
   if (!credential) {
     throw new Error("No workflow LLM credential found. Set OPENROUTER_API_KEY or OPENAI_API_KEY.");

package/src/workflows/index.ts

@@ -37,7 +37,14 @@ import { startWaitPoller } from "./wait-poller";
 // ─── Module-level singleton ────────────────────────────────
 
 let _registry: ExecutorRegistry | null = null;
-let slackMessageTriggerListenerInitialized = false;
+let eventTriggerListenersInitialized = false;
+
+/** Bus events that start workflows with a matching `event` trigger. Keep in sync with `TriggerConfigSchema`. */
+const EVENT_TRIGGER_NAMES = [
+  "slack.message",
+  "azure-devops.work_item.assigned",
+  "azure-devops.work_item.commented",
+] as const;
 
 function createBuiltInExecutorRegistry(): ExecutorRegistry {
   return createExecutorRegistry({
@@ -57,18 +64,20 @@ export function getExecutorRegistry(): ExecutorRegistry {
   return _registry;
 }
 
-function setupSlackMessageTriggerListener(): void {
-  if (slackMessageTriggerListenerInitialized) return;
+function setupEventTriggerListeners(): void {
+  if (eventTriggerListenersInitialized) return;
 
-  workflowEventBus.on("slack.message", (payload) => {
-    void handleEventTrigger("slack.message", payload, getExecutorRegistry()).catch((err) => {
-      console.error(
-        "[workflows] Failed to dispatch slack.message event trigger:",
-        scrubSecrets(err instanceof Error ? err.message : String(err)),
-      );
+  for (const eventName of EVENT_TRIGGER_NAMES) {
+    workflowEventBus.on(eventName, (payload) => {
+      void handleEventTrigger(eventName, payload, getExecutorRegistry()).catch((err) => {
+        console.error(
+          `[workflows] Failed to dispatch ${eventName} event trigger:`,
+          scrubSecrets(err instanceof Error ? err.message : String(err)),
+        );
+      });
     });
-  });
-  slackMessageTriggerListenerInitialized = true;
+  }
+  eventTriggerListenersInitialized = true;
 }
 
 /**
@@ -84,7 +93,7 @@ export async function initWorkflows(): Promise<void> {
 
   // 2. Wire up resume listener (task.completed / task.failed / task.cancelled)
   setupWorkflowResumeListener(workflowEventBus, _registry);
-  setupSlackMessageTriggerListener();
+  setupEventTriggerListeners();
 
   // 3. Recover incomplete runs (running + waiting) from previous lifecycle
   recoverIncompleteRuns(_registry).catch((err) => {

package/templates/extensions/README.md

@@ -14,6 +14,7 @@ Each folder holds exactly one `manifest.yaml`, `manifest.yml`, or `manifest.json
 | `notify-on-complete` | `post.task.completed`, `post.task.failed` | Posts a summary to a Slack channel |
 | `deploy-awareness` | `pre.task.create` | Appends a one-line note to new tasks while a Dokploy deploy is in progress |
 | `slack-reply-gate` | `pre.task.create` | Asks Jev (TypeSafe or OpenRouter) whether Lead should answer a Slack thread follow-up; in `enforce` drops the wake-up and marks the message :mute: |
+| `comms-adherence-gate` | `pre.tool.call` | Asks Jev (TypeSafe or OpenRouter) whether a Slack task's final output matches the requester's comms preferences and latest request; in `enforce` blocks a non-adherent completion once per task |
 | `require-verification-note` | `pre.tool.call` | Refuses completion without a `Verified:` line in the output |
 | `task-digest` | `post.task.completed`, `post.task.failed` | Ships the `task-digest-collect` script, the `task-digest-daily` schedule (09:00 UTC), the `task-digest-report` workflow, and the `task-digest-guide` skill |
 

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

@@ -0,0 +1,88 @@
+# 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.
+
+Install config:
+
+```json
+{ "mode": "shadow" }
+```
+
+Start in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`.
+
+## Modes
+
+| `mode` | Effect |
+|---|---|
+| `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. |
+
+## 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:
+
+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.
+
+## Decision
+
+The 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.
+
+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.
+
+## Jev transport
+
+Jev is reachable two ways. Both take the same request and return the same answer.
+
+| `provider` | Endpoint | Key | Model |
+|---|---|---|---|
+| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |
+| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |
+| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |
+
+Each verdict row records the `provider` that answered.
+
+## Fail open
+
+Every 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`.
+
+## 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.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `mode` | `shadow` | `off`, `shadow`, or `enforce` |
+| `threshold` | `0.5` | A dimension scoring below this fails |
+| `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) |
+| `model` | `jev-latest` | Jev model on TypeSafe |
+| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |
+| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |
+
+## Required secrets
+
+Read 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.
+
+- `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.
+
+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`.
+- `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>`.
+
+## 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.