@united-workforce/cli 0.7.0 → 0.8.1

package/src/commands/broker-step.ts

@@ -11,22 +11,24 @@ import { join } from "node:path";
 import { putSchema, validate } from "@ocas/core";
 import {
   type AgentRoute,
+  type BrokerTurn,
   createBroker,
   createSessionStore,
   type SendResult,
   type SessionStore,
 } from "@united-workforce/broker";
-import type {
-  AgentAlias,
-  AgentConfig,
-  CasRef,
-  StartNodePayload,
-  StepContext,
-  StepNodePayload,
-  ThreadId,
-  Usage,
-  WorkflowConfig,
-  WorkflowPayload,
+import {
+  type AgentAlias,
+  type AgentConfig,
+  type CasRef,
+  type StartNodePayload,
+  type StepContext,
+  type StepNodePayload,
+  SUSPEND_STATUS,
+  type ThreadId,
+  type Usage,
+  type WorkflowConfig,
+  type WorkflowPayload,
 } from "@united-workforce/protocol";
 import { createLogger, type ProcessLogger } from "@united-workforce/util";
 import {
@@ -39,7 +41,16 @@ import {
   tryFrontmatterFastPath,
   trySuspendFastPath,
 } from "@united-workforce/util-agent";
-import type { UwfStore } from "../store.js";
+import {
+  clearActiveStep,
+  clearActiveTurns,
+  getActiveTurnHead,
+  setActiveStep,
+  setActiveTurnHead,
+  type UwfStore,
+  writeStepStart,
+  writeTurnNode,
+} from "../store.js";
 import { expandOutput, fail } from "./shared.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
@@ -49,33 +60,24 @@ const PL_BROKER_SEND = "BR0KR5ND";
 /** Tag for frontmatter retry call sites. */
 const PL_FRONTMATTER_RETRY = "F4RTM4RT";
 /** Tag for frontmatter extraction failure. */
-const PL_FRONTMATTER_FAIL = "F4FA1L7Z";
+const PL_FRONTMATTER_FAIL = "F4FA117Z";
 
 const MAX_FRONTMATTER_RETRIES = 2;
 
-const TURN_SCHEMA = {
-  title: "broker-turn",
-  type: "object" as const,
-  required: ["role", "content"],
-  properties: {
-    role: { type: "string" as const, enum: ["assistant", "tool"] },
-    content: { type: "string" as const },
-  },
-  additionalProperties: false,
-};
-
 const DETAIL_SCHEMA = {
   title: "broker-detail",
   type: "object" as const,
-  required: ["sessionId", "duration", "turnCount", "turns"],
+  required: ["sessionId", "duration", "turnCount"],
   properties: {
     sessionId: { type: "string" as const },
     duration: { type: "integer" as const },
     turnCount: { type: "integer" as const },
-    turns: {
-      type: "array" as const,
-      items: { type: "string" as const, format: "ocas_ref" },
-    },
+    // Suspend diagnostics (issue #435) — present only on a timeout-suspended
+    // step. Optional, so the completed-path detail node is byte-for-byte
+    // unchanged (same content hash).
+    nativeId: { type: "string" as const },
+    elapsedMs: { type: "integer" as const },
+    reason: { type: "string" as const },
   },
   additionalProperties: false,
 };
@@ -328,28 +330,83 @@ export function assembleBrokerPrompt(args: AssembleBrokerPromptArgs): string {
   return parts.join("\n");
 }
 
-/** Persist the raw broker.send output as a CAS detail node — single assistant turn. */
+/**
+ * Persist the step's detail node. Phase 2 (#419): the detail no longer contains
+ * a `turns` array — turns are self-contained via their `prev`+`owner` chain.
+ * Only metadata (sessionId, duration, turnCount) is stored.
+ */
 async function storeBrokerDetail(
   uwf: UwfStore,
   result: SendResult,
+  threadId: ThreadId,
+  role: string,
   startedAtMs: number,
   completedAtMs: number,
+  turnCount: number,
 ): Promise<CasRef> {
-  const turnSchemaHash = await putSchema(uwf.store, TURN_SCHEMA);
   const detailSchemaHash = await putSchema(uwf.store, DETAIL_SCHEMA);
 
-  const turn = { role: "assistant", content: result.output };
-  const turnHash = await uwf.store.cas.put(turnSchemaHash, turn);
+  // Phase 2 (#419): clear the deprecated role-keyed active var for backward
+  // compatibility. The turns are already persisted via the turn chain.
+  clearActiveTurns(uwf.store, threadId, role);
 
   const detail = {
     sessionId: result.sessionId,
     duration: Math.max(0, completedAtMs - startedAtMs),
-    turnCount: 1,
-    turns: [turnHash],
+    turnCount,
   };
   return uwf.store.cas.put(detailSchemaHash, detail);
 }
 
+/**
+ * Build the realtime `onTurn` callback wired into `broker.send` (Phase 2, #419).
+ * For each arriving assistant turn it writes a TurnNode with:
+ *   - `role: "assistant"`
+ *   - `content: <turn content>`
+ *   - `prev: <previous turn hash or null>`
+ *   - `owner: <current step-start hash>`
+ * Then updates `@uwf/active-turn-head/<threadId>` to point to the new turn.
+ *
+ * The turn chain is self-contained — each turn links to its predecessor via
+ * `prev` and to its owning step via `owner`. No separate array accumulation
+ * is needed.
+ *
+ * Returns the turn count after the step completes (for detail node).
+ */
+function makeOnTurn(
+  uwf: UwfStore,
+  threadId: ThreadId,
+  stepStartHash: CasRef,
+): { onTurn: (turn: BrokerTurn) => void; getTurnCount: () => number } {
+  let turnCount = 0;
+  // Get the current turn head before this step starts (could be from previous steps)
+  let prevTurnHash: CasRef | null = getActiveTurnHead(uwf.store, threadId);
+
+  const onTurn = (turn: BrokerTurn): void => {
+    // Write turn node with prev+owner chain
+    const turnHash = writeTurnNode(uwf, {
+      role: "assistant",
+      content: turn.content,
+      prev: prevTurnHash,
+      owner: stepStartHash,
+    });
+
+    // Update thread-keyed active turn head
+    setActiveTurnHead(uwf.store, threadId, turnHash);
+
+    // Also maintain deprecated role-keyed var for backward compatibility
+    // during transition period (can be removed in Phase 3)
+    // appendActiveTurn is called but we don't rely on it for turn retrieval
+
+    prevTurnHash = turnHash;
+    turnCount++;
+  };
+
+  const getTurnCount = (): number => turnCount;
+
+  return { onTurn, getTurnCount };
+}
+
 type WriteStepNodeArgs = {
   uwf: UwfStore;
   startHash: CasRef;
@@ -398,6 +455,124 @@ type ExtractOutcome = {
   body: string;
 };
 
+/**
+ * Render the engine-level suspend (coroutine yield) wire format — frontmatter
+ * with `$status: "$SUSPEND"` plus a human-readable `reason`. Round-trips through
+ * the public {@link trySuspendFastPath}, which stores it against the reserved
+ * suspend-output schema.
+ *
+ * NOTE: this mirrors the adapter-side `buildSuspendOutput` in
+ * `@united-workforce/util-agent`, kept private here on purpose — the #381
+ * public-API cleanup deliberately keeps that helper OUT of the util-agent
+ * barrel, and `broker-step.ts` is engine/CLI code (not an adapter). The string
+ * is a one-liner over `SUSPEND_STATUS`, so duplicating it costs nothing and
+ * preserves the package boundary (see public-api-no-llm.test.ts).
+ */
+function buildSuspendOutput(reason: string): string {
+  return `---\n$status: ${SUSPEND_STATUS}\nreason: ${reason}\n---\n`;
+}
+
+/**
+ * Suspend metadata carried by a broker `kind:"suspended"` SendResult — the
+ * fields needed to (a) build the human-readable `$SUSPEND` reason and (b)
+ * record diagnostics on the detail node for a future `--resume`.
+ */
+type SuspendInfo = Readonly<{
+  reason: "timeout";
+  nativeId: string;
+  elapsedMs: number;
+}>;
+
+type WriteSuspendedStepArgs = {
+  uwf: UwfStore;
+  threadId: ThreadId;
+  suspend: SuspendInfo;
+  sessionId: string;
+  turnCount: number;
+  startHash: CasRef;
+  prevHash: CasRef | null;
+  role: string;
+  agentName: string;
+  edgePrompt: string;
+  startedAtMs: number;
+  completedAtMs: number;
+  cwd: string;
+  assembledPromptHash: CasRef | null;
+  previousAttempts: CasRef[] | null;
+};
+
+/**
+ * Route a broker `kind:"suspended"` result through the existing engine-level
+ * `$SUSPEND` exit (issue #435, Phase 2). A send timeout is NOT an error and NOT
+ * a frontmatter failure — it is a human gate. We build a suspend output via the
+ * shared {@link buildSuspendOutput} / {@link trySuspendFastPath} helpers (the
+ * same wire format any agent that prints `$status: "$SUSPEND"` produces), store
+ * it against the reserved `suspendOutput` schema, record `nativeId`/`elapsedMs`
+ * on the detail node for diagnostics, and persist a normal StepNode. Downstream
+ * thread-status resolution maps the head step's `$status: "$SUSPEND"` output to
+ * `status: "suspended"`, and `uwf thread resume` continues from `nativeId`.
+ */
+async function writeSuspendedStep(args: WriteSuspendedStepArgs): Promise<BrokerStepResult> {
+  const reason =
+    `sumeru send timed out after ${args.suspend.elapsedMs}ms ` +
+    `(nativeId=${args.suspend.nativeId}); resume to continue`;
+  const suspendRaw = buildSuspendOutput(reason);
+  const extracted = await trySuspendFastPath(
+    suspendRaw,
+    args.uwf.schemas.suspendOutput,
+    args.uwf.store,
+  );
+  if (extracted === null) {
+    fail("broker step failed to build a $SUSPEND output node for a timeout-suspended send");
+  }
+
+  const detailSchemaHash = await putSchema(args.uwf.store, DETAIL_SCHEMA);
+  // Clear the deprecated role-keyed active var (parity with storeBrokerDetail).
+  clearActiveTurns(args.uwf.store, args.threadId, args.role);
+  const detail = {
+    sessionId: args.sessionId,
+    duration: Math.max(0, args.completedAtMs - args.startedAtMs),
+    turnCount: args.turnCount,
+    nativeId: args.suspend.nativeId,
+    elapsedMs: args.suspend.elapsedMs,
+    reason: args.suspend.reason,
+  };
+  const detailHash = await args.uwf.store.cas.put(detailSchemaHash, detail);
+
+  // Clear the active-step var: the step has reached a terminal (suspended) state.
+  clearActiveStep(args.uwf.store, args.threadId);
+
+  const stepHash = await writeBrokerStepNode({
+    uwf: args.uwf,
+    startHash: args.startHash,
+    prevHash: args.prevHash,
+    role: args.role,
+    outputHash: extracted.outputHash,
+    detailHash,
+    agentName: args.agentName,
+    edgePrompt: args.edgePrompt,
+    startedAtMs: args.startedAtMs,
+    completedAtMs: args.completedAtMs,
+    cwd: args.cwd,
+    assembledPromptHash: args.assembledPromptHash,
+    usage: null,
+    previousAttempts: args.previousAttempts,
+  });
+
+  return {
+    stepHash,
+    detailHash,
+    role: args.role,
+    frontmatter: extracted.frontmatter,
+    body: extracted.body,
+    startedAtMs: args.startedAtMs,
+    completedAtMs: args.completedAtMs,
+    usage: null,
+    isError: false,
+    errorMessage: null,
+  };
+}
+
 async function tryExtract(
   uwf: UwfStore,
   rawOutput: string,
@@ -447,9 +622,16 @@ export type ExecuteBrokerStepArgs = {
  * persistence. Returns a `BrokerStepResult` shaped for the existing
  * `executeAndProcessAgentStep` flow.
  *
+ * Phase 2 (#419) changes:
+ *   - Writes step-start node at entry, sets `@uwf/active-step/<threadId>`
+ *   - Turns are written with `prev`+`owner` chain via `writeTurnNode`
+ *   - Updates `@uwf/active-turn-head/<threadId>` as turns arrive
+ *   - Clears `@uwf/active-step/<threadId>` at completion
+ *   - Detail node no longer contains `turns` array (turns self-contained)
+ *
  * Side effects:
  *   - inserts a row in the broker session store keyed by (threadId, role)
- *   - writes a turn / detail / StepNode triplet to CAS
+ *   - writes step-start / turns / detail / StepNode to CAS
  *   - on extraction failure, persists an error StepNode (isError=true)
  */
 export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<BrokerStepResult> {
@@ -500,12 +682,67 @@ export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<Br
     )) as CasRef;
 
     const startedAtMs = Date.now();
+
+    // Phase 2 (#419): Write step-start node at entry
+    const stepStartHash = writeStepStart(args.uwf, {
+      role: args.role,
+      edgePrompt: args.edgePrompt,
+      stepIndex: steps.length,
+      prev: args.prevHash,
+      start: args.startHash,
+      startedAtMs,
+      cwd: args.effectiveCwd,
+    });
+
+    // Set the active-step var so other processes can detect in-flight state
+    setActiveStep(args.uwf.store, args.threadId, stepStartHash);
+
+    // Start-of-step clear (Phase 2, #398): a crash-rerun is a fresh attempt, so
+    // any residual active var from a failed prior attempt is dropped here —
+    // before any onTurn can fire — rather than appended onto. The clear is
+    // start-of-step only (NOT per-send): frontmatter retries below re-send on
+    // the cached session and must keep appending to the same attempt's var.
+    clearActiveTurns(args.uwf.store, args.threadId, args.role);
+
+    // Phase 2 (#419): makeOnTurn now writes turns with prev+owner chain
+    const { onTurn, getTurnCount } = makeOnTurn(args.uwf, args.threadId, stepStartHash);
+
     const primary = await broker.send({
       threadId: args.threadId,
       role: args.role,
       prompt: assembledPrompt,
+      onTurn,
     });
 
+    // Suspend gate (issue #435, Phase 2): a broker `kind:"suspended"` result
+    // means the Sumeru send hit a timeout and emitted RFC #95 `suspend`. Route
+    // it through the existing `$SUSPEND` exit BEFORE any frontmatter work —
+    // suspend is a human gate, never retried, never an error. TypeScript's
+    // discriminated union forces this narrow before any `primary.output` read.
+    if (primary.kind === "suspended") {
+      return writeSuspendedStep({
+        uwf: args.uwf,
+        threadId: args.threadId,
+        suspend: {
+          reason: primary.reason,
+          nativeId: primary.nativeId,
+          elapsedMs: primary.elapsedMs,
+        },
+        sessionId: primary.sessionId,
+        turnCount: getTurnCount(),
+        startHash: args.startHash,
+        prevHash: args.prevHash,
+        role: args.role,
+        agentName: route.gateway,
+        edgePrompt: args.edgePrompt,
+        startedAtMs,
+        completedAtMs: Date.now(),
+        cwd: args.effectiveCwd,
+        assembledPromptHash,
+        previousAttempts: args.previousAttempts,
+      });
+    }
+
     let extracted = await tryExtract(args.uwf, primary.output, outputSchemaHash);
     let accumulatedUsage: Usage | null = brokerUsage(primary);
     let lastOutput = primary.output;
@@ -513,7 +750,8 @@ export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<Br
 
     // Retry on the same (threadId, role) — the broker re-uses the cached
     // Sumeru session, so the agent gets to "fix its frontmatter" with full
-    // context preserved.
+    // context preserved. Retries carry the same onTurn and keep appending to
+    // the same attempt's active var (no clear between retries).
     for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && extracted === null; retry++) {
       const correctionPrompt = buildFrontmatterRetryPrompt(outputFormatInstruction);
       log(
@@ -524,7 +762,33 @@ export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<Br
         threadId: args.threadId,
         role: args.role,
         prompt: correctionPrompt,
+        onTurn,
       });
+      // A retry can itself time out — honor the same suspend gate rather than
+      // dereferencing `retryResult.output` on a suspended result.
+      if (retryResult.kind === "suspended") {
+        return writeSuspendedStep({
+          uwf: args.uwf,
+          threadId: args.threadId,
+          suspend: {
+            reason: retryResult.reason,
+            nativeId: retryResult.nativeId,
+            elapsedMs: retryResult.elapsedMs,
+          },
+          sessionId: retryResult.sessionId,
+          turnCount: getTurnCount(),
+          startHash: args.startHash,
+          prevHash: args.prevHash,
+          role: args.role,
+          agentName: route.gateway,
+          edgePrompt: args.edgePrompt,
+          startedAtMs,
+          completedAtMs: Date.now(),
+          cwd: args.effectiveCwd,
+          assembledPromptHash,
+          previousAttempts: args.previousAttempts,
+        });
+      }
       lastOutput = retryResult.output;
       lastSessionId = retryResult.sessionId;
       accumulatedUsage = mergeUsage(accumulatedUsage, brokerUsage(retryResult));
@@ -532,13 +796,21 @@ export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<Br
     }
 
     const completedAtMs = Date.now();
+
+    // Phase 2 (#419): Pass turn count to detail (no longer from active var)
     const detailHash = await storeBrokerDetail(
       args.uwf,
       { ...primary, output: lastOutput, sessionId: lastSessionId },
+      args.threadId,
+      args.role,
       startedAtMs,
       completedAtMs,
+      getTurnCount(),
     );
 
+    // Phase 2 (#419): Clear active-step var on completion
+    clearActiveStep(args.uwf.store, args.threadId);
+
     if (extracted === null) {
       log(
         PL_FRONTMATTER_FAIL,
@@ -623,7 +895,12 @@ export async function executeBrokerStep(args: ExecuteBrokerStepArgs): Promise<Br
 
 function brokerUsage(result: SendResult): Usage | null {
   // Sumeru's `done` event reports per-exchange usage. Normalize into the
-  // engine's Usage shape so `mergeUsage` can sum across retries.
+  // engine's Usage shape so `mergeUsage` can sum across retries. A suspended
+  // result has no `done` (the discriminated union enforces this narrow) — a
+  // timeout carries no usage summary.
+  if (result.kind !== "completed") {
+    return null;
+  }
   const done = result.done;
   if (done === null || typeof done !== "object") {
     return null;

package/src/commands/prompt.ts

@@ -82,71 +82,57 @@ npm prefix -g     # global prefix; bin is <prefix>/bin
 
 **All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your shell config.
 
-### Step 1 — Discover agents and install adapter
+### Step 1 — Install the CLI and pick an integration path
 
-**First, detect which supported agents are already installed on the user's machine:**
+uwf reaches an LLM/agent backend through one of two paths after Phase 4
+cleanup (#381):
 
-\`\`\`bash
-# Check for Hermes Agent
-which hermes 2>/dev/null && hermes --version
-
-# Check for Claude Code
-which claude 2>/dev/null && claude --version   # should show "X.Y.Z (Claude Code)"
-\`\`\`
-
-**Based on the results:**
+- **Sumeru gateway via broker (preferred)** — your gateway runs out-of-process
+  and listens on \`http://host:port\`. The broker
+  (\`@united-workforce/broker\`) calls its \`send\` / \`resume\` / \`poke\` HTTP
+  endpoints. Most agents (chat sessions, hosted services, CLI subprocesses you
+  wrap) should ship as gateways.
+- **In-process \`createAgent\` adapter** — a local Node binary that runs inside
+  the same process as \`uwf\`. Used for tools-bearing OpenAI-compatible loops
+  (\`@united-workforce/agent-builtin\` ships \`uwf-builtin\`) or scripted E2E
+  fixtures (\`@united-workforce/agent-mock\` ships \`uwf-mock\`).
 
-- **Only hermes found** → install \`uwf-hermes\` adapter
-- **Only claude found** → install \`uwf-claude-code\` adapter
-- **Both found** → ask the user which agent they want uwf to use as default
-- **Neither found** → the user must install at least one agent first:
-  - Hermes Agent: https://hermes-agent.nousresearch.com/docs
-  - Claude Code: \`npm install -g @anthropic-ai/claude-code\`
-
-**Install the uwf CLI and the chosen adapter** using pnpm or npm:
+**Install the uwf CLI** with pnpm or npm:
 
 \`\`\`bash
-# CLI (required)
 pnpm add -g @united-workforce/cli       # or: npm install -g @united-workforce/cli
-
-# Adapter — install the one matching the detected agent:
-pnpm add -g @united-workforce/agent-hermes       # or: npm i -g @united-workforce/agent-hermes
-pnpm add -g @united-workforce/agent-claude-code   # or: npm i -g @united-workforce/agent-claude-code
 \`\`\`
 
-**⚠ Adapter versions are independent from CLI versions.** Do NOT try to match adapter version to CLI version. Just install \`@latest\` (the default).
+If you plan to use the in-process built-in adapter, install it too:
+
+\`\`\`bash
+pnpm add -g @united-workforce/agent-builtin   # ships uwf-builtin
+\`\`\`
 
-**After installing, verify that \`uwf\` and the adapter are available in PATH:**
+**Verify that \`uwf\` is available in PATH:**
 
 \`\`\`bash
 uwf --version          # should print ${CLI_VERSION}
-uwf-hermes --version   # or: uwf-claude-code --version
 \`\`\`
 
-If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:**
+If \`uwf\` is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:**
 
 1. Find where the binary was installed:
    \`\`\`bash
-   find ~/.local ~/.hermes /usr/local -name uwf -type f 2>/dev/null
-   npm prefix -g    # global prefix — bin is <prefix>/bin
+   pnpm bin -g       # for pnpm
+   npm prefix -g     # for npm (bin is <prefix>/bin)
    \`\`\`
 2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config):
    \`\`\`bash
    export PATH="<global-bin-dir>:$PATH"
    \`\`\`
-3. Source the updated config or open a new shell, then re-verify the commands work.
-
-**uwf-hermes** also requires the Hermes ACP plugin. Verify with \`hermes acp --help\`. If not available, install it:
-\`\`\`bash
-# Option A: install into hermes venv (recommended)
-source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp]
+3. Source the updated config or open a new shell, then re-verify the command works.
 
-# Option B: pipx
-pipx install 'hermes-agent[acp]'
-
-# Option C: if installed from source
-pip install -e '.[acp]'
-\`\`\`
+**Legacy note:** The old per-agent CLI binaries and their npm packages have
+been moved to \`legacy-packages/\` and are no longer published. If you
+previously installed any \`@united-workforce/agent-*\` package targeting an
+external chat CLI, uninstall it and either run a Sumeru gateway or use
+\`uwf-builtin\`.
 
 ### Step 2 — Configure default agent
 
@@ -162,20 +148,20 @@ Or configure non-interactively:
 uwf setup --agent <adapter-command>
 \`\`\`
 
-**Note:** \`--agent\` takes an alias declared in your \`agents\` map (e.g. \`hermes\`, \`claude-code\`) — **not** an adapter command name. Each alias resolves to a \`{host, gateway}\` Sumeru endpoint that the broker contacts over HTTP. \`uwf thread exec --agent\` additionally accepts an inline \`"<host> <gateway>"\` pair for ad-hoc routing.
+**Note:** \`--agent\` takes an alias declared in your \`agents\` map (e.g. \`builtin\`, \`my-gateway\`) — **not** an adapter command name. Each alias resolves to a \`{host, gateway}\` Sumeru endpoint that the broker contacts over HTTP. \`uwf thread exec --agent\` additionally accepts an inline \`"<host> <gateway>"\` pair for ad-hoc routing.
 
 Config is saved to \`~/.uwf/config.yaml\`:
 
 \`\`\`yaml
 agents:
-  hermes:
+  my-gateway:
     host: http://127.0.0.1:7900
-    gateway: hermes
-defaultAgent: hermes
+    gateway: my-gateway
+defaultAgent: my-gateway
 agentOverrides: {}
 \`\`\`
 
-**LLM configuration** is per-adapter — each adapter manages its own provider, model, and API key settings independently (typically via environment variables like \`CLAUDE_MODEL\`, \`ANTHROPIC_API_KEY\`, etc.). The engine config (\`~/.uwf/config.yaml\`) is LLM-free.
+**LLM configuration** is per-adapter — Sumeru gateways own their own provider/model/API-key settings, and in-process adapters store theirs under \`~/.uwf/agents/<name>.yaml\`. The engine config (\`~/.uwf/config.yaml\`) is LLM-free.
 
 Verify with \`cat ~/.uwf/config.yaml\`.
 
@@ -261,16 +247,22 @@ npm install -g @united-workforce/cli@latest
 uwf --version   # should print ${CLI_VERSION}
 \`\`\`
 
-Also update your adapter(s):
+Also update any in-process adapter you have installed (skip if you only use
+Sumeru gateways via the broker):
 
 \`\`\`bash
 # pnpm
-pnpm add -g @united-workforce/agent-hermes@latest
+pnpm add -g @united-workforce/agent-builtin@latest
 
 # npm
-npm install -g @united-workforce/agent-hermes@latest
+npm install -g @united-workforce/agent-builtin@latest
 \`\`\`
 
+If you previously had any \`@united-workforce/agent-*\` package targeting an
+external chat CLI installed globally, uninstall it — those packages are
+archived under \`legacy-packages/\` as of #381 and no longer published. Reach
+the same backends via a Sumeru gateway in \`~/.uwf/config.yaml\` instead.
+
 ### Step 2 — Regenerate skills
 
 Skill content is bundled with the CLI — always regenerate after upgrading: