@yeaft/webchat-agent 0.1.525 → 0.1.527

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.525",
+  "version": "0.1.527",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/groups/group-store.js

@@ -26,7 +26,7 @@ import {
 } from 'fs';
 import { join } from 'path';
 import { writeAtomic, openLog } from '../storage/index.js';
-import { nextMsgId, isReservedVpId, ReservedVpIdError } from './ids.js';
+import { nextMsgId, isReservedVpId, ReservedVpIdError, validateVpId, InvalidVpIdError } from './ids.js';
 
 const GROUP_FILE = 'group.json';
 const MESSAGES_DIR = 'messages';
@@ -113,9 +113,13 @@ export function createGroup(groupsRoot, spec) {
   const roster = Array.isArray(spec.roster) ? spec.roster.slice() : [];
   for (const v of roster) {
     if (isReservedVpId(v)) throw new ReservedVpIdError(v);
+    const verdict = validateVpId(v);
+    if (!verdict.ok) throw new InvalidVpIdError(v, verdict.reason);
   }
-  if (spec.defaultVpId && isReservedVpId(spec.defaultVpId)) {
-    throw new ReservedVpIdError(spec.defaultVpId);
+  if (spec.defaultVpId) {
+    if (isReservedVpId(spec.defaultVpId)) throw new ReservedVpIdError(spec.defaultVpId);
+    const dverdict = validateVpId(spec.defaultVpId);
+    if (!dverdict.ok) throw new InvalidVpIdError(spec.defaultVpId, dverdict.reason);
   }
   const meta = {
     id: spec.id,

package/unify/groups/ids.js

@@ -69,3 +69,61 @@ export class ReservedVpIdError extends Error {
     this.vpId = vpId;
   }
 }
+
+/**
+ * Character + shape whitelist for a user-facing vpId. Stricter than
+ * `parseMentions` (Postel's law: be lenient on input, be strict on storage).
+ *
+ * Rules (task-334d, absorbing 334b follow-up #1):
+ *   - Must be a non-empty string
+ *   - Length 1..40
+ *   - Characters: `[A-Za-z0-9_-]` only
+ *   - Must NOT start with `_` (underscore reserved for future system roles)
+ *   - Must NOT be purely digits
+ *   - Must NOT be a reserved vpId (delegates to isReservedVpId)
+ *
+ * Returns `{ ok, reason? }`. The callsites that want a boolean use
+ * `isValidVpId(id)` (truthy only when ok). Error strings are stable so UI
+ * can key on them for i18n (prev-1 nit: UX-friendly messages come later;
+ * this layer exposes raw reasons).
+ */
+const VP_ID_RE = /^[A-Za-z0-9_-]+$/;
+const PURE_DIGITS_RE = /^[0-9]+$/;
+const VP_ID_MAX_LEN = 40;
+
+export function validateVpId(id) {
+  if (!id || typeof id !== 'string') {
+    return { ok: false, reason: 'empty_or_non_string' };
+  }
+  if (id.length > VP_ID_MAX_LEN) {
+    return { ok: false, reason: 'too_long' };
+  }
+  if (!VP_ID_RE.test(id)) {
+    return { ok: false, reason: 'illegal_character' };
+  }
+  if (id.startsWith('_')) {
+    return { ok: false, reason: 'underscore_prefix_reserved' };
+  }
+  if (PURE_DIGITS_RE.test(id)) {
+    return { ok: false, reason: 'pure_digits' };
+  }
+  if (isReservedVpId(id)) {
+    return { ok: false, reason: 'reserved' };
+  }
+  return { ok: true };
+}
+
+/** Convenience boolean wrapper for call-sites that don't care about the reason. */
+export function isValidVpId(id) {
+  return validateVpId(id).ok;
+}
+
+/** Thrown by CRUD entry points on an invalid (non-reserved) vpId shape. */
+export class InvalidVpIdError extends Error {
+  constructor(vpId, reason) {
+    super(`vpId "${vpId}" is invalid (${reason})`);
+    this.name = 'InvalidVpIdError';
+    this.vpId = vpId;
+    this.reason = reason;
+  }
+}

package/unify/groups/index.js

@@ -44,4 +44,7 @@ export {
   isReservedVpId,
   RESERVED_VP_IDS,
   ReservedVpIdError,
+  isValidVpId,
+  validateVpId,
+  InvalidVpIdError,
 } from './ids.js';

package/unify/groups/roster.js

@@ -12,7 +12,7 @@
  * and optionally notify listeners.
  */
 
-import { isReservedVpId, ReservedVpIdError } from './ids.js';
+import { isReservedVpId, ReservedVpIdError, validateVpId, InvalidVpIdError } from './ids.js';
 
 /** Returns a cloned roster array with `vpId` appended if not already present. */
 export function addVp(meta, vpId) {
@@ -22,6 +22,10 @@ export function addVp(meta, vpId) {
   if (isReservedVpId(vpId)) {
     throw new ReservedVpIdError(vpId);
   }
+  const verdict = validateVpId(vpId);
+  if (!verdict.ok) {
+    throw new InvalidVpIdError(vpId, verdict.reason);
+  }
   const roster = meta.roster.slice();
   if (!roster.includes(vpId)) roster.push(vpId);
   const defaultVpId = meta.defaultVpId || roster[0] || null;

package/unify/routing/index.js

@@ -0,0 +1,21 @@
+/**
+ * routing/ — VP-side @-forward dispatch (task-334d).
+ *
+ * Layered on top of 334b Group Coordinator:
+ *   - loop-guard: chain-depth + rate-window protection
+ *   - router:     route_forward → coordinator.ingest wrapper with guard,
+ *                  self-reject, task.members forwarding, and causedBy chain.
+ *
+ * See agent/unify/tools/route-forward.js for the VP-facing tool.
+ */
+
+export {
+  createLoopGuard,
+  extendCausedBy,
+  MAX_CHAIN_DEPTH,
+  DEFAULT_WINDOW_MS,
+  DEFAULT_MAX_HITS_PER_WINDOW,
+  DEFAULT_MAX_KEYS,
+  DEFAULT_TTL_MULTIPLIER,
+} from './loop-guard.js';
+export { createRouter } from './router.js';

package/unify/routing/loop-guard.js

@@ -0,0 +1,228 @@
+/**
+ * loop-guard.js — Routing loop protection for task-334d.
+ *
+ * Prevents two classes of runaway fan-out:
+ *
+ *   1. Chain depth — a message's `causedBy` chain (A → @B → @C → @A …) must
+ *      not exceed a max depth. Each route_forward call stamps the outbound
+ *      envelope's `meta.causedBy` with a chain of msgIds, and the guard
+ *      rejects when the chain length would exceed MAX_CHAIN_DEPTH (10).
+ *
+ *   2. Rate throttle — within a sliding window (WINDOW_MS = 5000, default
+ *      MAX_HITS_PER_WINDOW = 8), a single (groupId, vpId) target may be
+ *      @-forwarded at most N times. On overflow, the forward returns a
+ *      `throttled` error and does NOT dispatch. The counter uses a simple
+ *      ring (timestamps array) so expired hits are collected on insert.
+ *
+ * Both limits are per-group-per-target; chains are tracked per msgId root.
+ * The guard is a pure in-memory helper — no persistence — because the
+ * threat model is one runaway turn storm within a single process tick.
+ *
+ * Long-running process hygiene (N1, task-334d-followup):
+ *   The `hits` Map is keyed by "groupId::vpId" and would otherwise grow
+ *   unboundedly over a long session. Two complementary bounds:
+ *     - TTL sweep: on each NEW key insert, drop entries whose most
+ *       recent hit is older than `ttlMultiplier × windowMs` (default 2×).
+ *       Those entries can never throttle anyone regardless — their rate
+ *       window is already fully expired. Amortised O(n) but only on new
+ *       keys, so normal hot-path cost stays O(1).
+ *     - LRU cap: after the TTL sweep, if size > maxKeys (default 1000)
+ *       the Map's insertion-order head (oldest-used key) is evicted until
+ *       back under the cap. `check()` and `record()` both `touch()` a key
+ *       (delete+re-set) so recency is refreshed on every access.
+ *   Behavior invariants preserved: the `'all'` broadcast sentinel, the
+ *   `now()` injection seam, and the chain-depth check are untouched — only
+ *   the eviction path is new.
+ *
+ * Integration contract (routing/router.js):
+ *   - router stamps envelope.meta.causedBy = [...prevChain, currentMsgId]
+ *   - router calls `guard.check({ groupId, targetVpId, chain })` BEFORE
+ *     calling coordinator.deliver; on `{ ok: false, reason }` returns a
+ *     tool-level error.
+ *   - on ok=true, router calls `guard.record({ groupId, targetVpId })` to
+ *     advance the rate counter.
+ */
+
+export const MAX_CHAIN_DEPTH = 10;
+export const DEFAULT_WINDOW_MS = 5_000;
+export const DEFAULT_MAX_HITS_PER_WINDOW = 8;
+export const DEFAULT_MAX_KEYS = 1_000;
+export const DEFAULT_TTL_MULTIPLIER = 2;
+
+/**
+ * Build a new loop guard. Safe to share across a single web-bridge process.
+ *
+ * @param {{
+ *   maxChainDepth?: number,
+ *   windowMs?: number,
+ *   maxHitsPerWindow?: number,
+ *   maxKeys?: number,                  // N1: LRU cap (default 1000)
+ *   ttlMultiplier?: number,            // N1: evict keys idle > ttlMultiplier*windowMs
+ *   now?: () => number,                // injectable for tests
+ * }} [options]
+ */
+export function createLoopGuard(options = {}) {
+  const maxChainDepth = options.maxChainDepth ?? MAX_CHAIN_DEPTH;
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  const maxHits = options.maxHitsPerWindow ?? DEFAULT_MAX_HITS_PER_WINDOW;
+  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+  const ttlMultiplier = options.ttlMultiplier ?? DEFAULT_TTL_MULTIPLIER;
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+
+  /** Map<"groupId::vpId", number[]> — sorted ascending timestamps.
+   * Map insertion order doubles as LRU recency: touching (delete+set) on
+   * every access keeps the oldest-used entry at the front for eviction. */
+  const hits = new Map();
+  let evictions = 0;
+
+  function key(groupId, vpId) { return `${groupId}::${vpId}`; }
+
+  function trim(arr, cutoff) {
+    let i = 0;
+    while (i < arr.length && arr[i] < cutoff) i += 1;
+    if (i > 0) arr.splice(0, i);
+  }
+
+  /**
+   * Touch a key → move to the Map's insertion tail (most-recently-used).
+   * Used on BOTH check() and record() paths so a blocked-but-checked
+   * target is kept warm as long as something keeps referencing it.
+   */
+  function touch(k, arr) {
+    hits.delete(k);
+    hits.set(k, arr);
+  }
+
+  /**
+   * Opportunistic TTL sweep: drop keys whose last hit is older than
+   * ttlMultiplier × windowMs (i.e. their rate window is fully expired and
+   * stale). Called on insert to amortise cleanup across normal traffic,
+   * so we never scan on the hot read path.
+   */
+  function sweepExpired() {
+    const ttlCutoff = now() - ttlMultiplier * windowMs;
+    for (const [k, arr] of hits) {
+      // arr is sorted ascending; the tail is the most-recent hit.
+      const last = arr.length > 0 ? arr[arr.length - 1] : -Infinity;
+      if (last < ttlCutoff) {
+        hits.delete(k);
+        evictions += 1;
+      }
+    }
+  }
+
+  /**
+   * Enforce the hard LRU cap. Called on insert AFTER sweepExpired so
+   * only genuinely hot but stale-enough entries get evicted.
+   */
+  function enforceCap() {
+    while (hits.size > maxKeys) {
+      const oldest = hits.keys().next().value;
+      if (oldest === undefined) break;
+      hits.delete(oldest);
+      evictions += 1;
+    }
+  }
+
+  return {
+    /**
+     * Check whether a forward to (groupId, vpId) with the supplied causedBy
+     * chain is permitted. Does NOT record — call record() after the caller
+     * decides to proceed (keeps dry-run / simulation honest).
+     *
+     * @param {{ groupId:string, targetVpId:string, chain?:string[] }} args
+     * @returns {{ ok:true } | { ok:false, reason:'chain_depth_exceeded'|'throttled', detail?:any }}
+     */
+    check({ groupId, targetVpId, chain = [] }) {
+      if (!groupId || !targetVpId) {
+        return { ok: false, reason: 'chain_depth_exceeded', detail: { missing: true } };
+      }
+      if (Array.isArray(chain) && chain.length >= maxChainDepth) {
+        return {
+          ok: false,
+          reason: 'chain_depth_exceeded',
+          detail: { depth: chain.length, limit: maxChainDepth },
+        };
+      }
+      const k = key(groupId, targetVpId);
+      const arr = hits.get(k);
+      if (arr) {
+        const cutoff = now() - windowMs;
+        trim(arr, cutoff);
+        // Refresh LRU recency — a repeatedly-probed hot target should not
+        // be evicted just because it never crosses into record().
+        touch(k, arr);
+        if (arr.length >= maxHits) {
+          return {
+            ok: false,
+            reason: 'throttled',
+            detail: { hits: arr.length, limit: maxHits, windowMs },
+          };
+        }
+      }
+      return { ok: true };
+    },
+
+    /** Record a successful forward — advances the rate counter. */
+    record({ groupId, targetVpId }) {
+      if (!groupId || !targetVpId) return;
+      const k = key(groupId, targetVpId);
+      let arr = hits.get(k);
+      const creating = !arr;
+      if (!arr) {
+        arr = [];
+        hits.set(k, arr);
+      }
+      const cutoff = now() - windowMs;
+      trim(arr, cutoff);
+      arr.push(now());
+      // Refresh LRU recency for both existing and new keys.
+      touch(k, arr);
+      // On *new* key creation, opportunistically clean up: first drop
+      // fully-expired entries (cheap, bounds unbounded growth), then
+      // enforce the hard cap. Skip on the update path to keep hot-loop
+      // cost O(1).
+      if (creating) {
+        sweepExpired();
+        enforceCap();
+      }
+    },
+
+    /** Snapshot for tests / debug. */
+    snapshot() {
+      const out = {};
+      for (const [k, arr] of hits) out[k] = arr.slice();
+      return {
+        hits: out,
+        maxChainDepth,
+        windowMs,
+        maxHits,
+        maxKeys,
+        ttlMultiplier,
+        size: hits.size,
+        evictions,
+      };
+    },
+
+    /** Wipe all counters (tests). */
+    reset() { hits.clear(); evictions = 0; },
+  };
+}
+
+/**
+ * Build a causedBy chain array from the inbound envelope + the current msgId.
+ * Returns a fresh array (no mutation of envelope).
+ *
+ * @param {any} inboundEnvelope  — envelope that the VP is currently handling
+ * @param {string} currentMsgId  — the NEW outbound msg about to be emitted
+ */
+export function extendCausedBy(inboundEnvelope, currentMsgId) {
+  const prev = inboundEnvelope?.msg?.meta?.causedBy;
+  const chain = Array.isArray(prev) ? prev.slice() : [];
+  // Also include the inbound msgId as the direct cause, if present and not
+  // already in the chain.
+  const inboundId = inboundEnvelope?.msg?.id;
+  if (inboundId && !chain.includes(inboundId)) chain.push(inboundId);
+  if (currentMsgId && !chain.includes(currentMsgId)) chain.push(currentMsgId);
+  return chain;
+}

package/unify/routing/router.js

@@ -0,0 +1,174 @@
+/**
+ * router.js — VP-side @-forward dispatch (task-334d).
+ *
+ * Wraps GroupCoordinator with the extra rules that apply when the sender is
+ * a VP (not a user). Architecture §6:
+ *
+ *   - VPs do NOT trigger text-@-routing. Free-text @foo from a VP is purely
+ *     surface noise. To hand off a turn, a VP must call the `route_forward`
+ *     tool — which lands here.
+ *   - route_forward(to, text, reason?) MUST go through Coordinator.dispatch
+ *     so @all fan-out caps, task.members filtering, and persistence stay
+ *     consistent with user-initiated routing.
+ *   - Self-forward (to === senderVpId) is a hard tool-level error; VPs
+ *     should "speak" via normal turn output, not route_forward.
+ *   - Loop guard: chain depth + rate throttle (see loop-guard.js).
+ *
+ * Router stamps `meta.causedBy` with the full chain so downstream Coordinator
+ * events carry provenance, and so the guard can refuse runaway chains even
+ * after the sending VP finishes its own turn.
+ *
+ * Hard constraints (inherited from PM directive):
+ *   (a) Does NOT touch RoleInstance state machine internals (that's 334c).
+ *   (b) Does NOT touch live-diff (334h).
+ *   (c) Persistence routes through group.appendMessage via Coordinator.
+ *   (d) Tool schema uses defineTool (agent/unify/tools/types.js).
+ */
+
+import { isMember } from '../groups/roster.js';
+import { createLoopGuard, extendCausedBy } from './loop-guard.js';
+
+/**
+ * Build a router bound to a single GroupCoordinator + loop guard.
+ *
+ * @param {{
+ *   coordinator: import('../groups/coordinator.js').GroupCoordinator,
+ *   guard?: ReturnType<typeof createLoopGuard>,
+ *   now?: () => number,
+ * }} deps
+ */
+export function createRouter(deps = {}) {
+  const { coordinator } = deps;
+  if (!coordinator || typeof coordinator.ingest !== 'function') {
+    throw new Error('createRouter: coordinator (with ingest()) is required');
+  }
+  const guard = deps.guard || createLoopGuard({ now: deps.now });
+
+  /**
+   * Forward a message from a VP to another VP (or @all). Routes through
+   * Coordinator so all MVP rules hold (fanout cap, task.members, persist).
+   *
+   * @param {{
+   *   from: string,           // sender vpId (required; never 'user')
+   *   to: string,              // target vpId OR 'all'
+   *   text: string,
+   *   reason?: string,         // optional human-readable rationale, stamped on meta
+   *   taskId?: string|null,
+   *   inboundEnvelope?: any,   // the envelope the sender is currently handling
+   *                             // (drives causedBy chain & loop guard)
+   * }} args
+   * @param {{ taskMembers?: string[] }} [opts]  — forwarded to coordinator.ingest
+   * @returns {{
+   *   ok: boolean,
+   *   error?: string,
+   *   dispatched?: string[],
+   *   report?: import('../groups/coordinator.js').DispatchReport,
+   * }}
+   */
+  function forward(args, opts = {}) {
+    if (!args || typeof args !== 'object') {
+      return { ok: false, error: 'args_required' };
+    }
+    const from = args.from;
+    const to = args.to;
+    const text = args.text;
+
+    if (!from || typeof from !== 'string') {
+      return { ok: false, error: 'from_required' };
+    }
+    if (from === 'user') {
+      // Users don't use route_forward — they type @ in chat. Policy guard.
+      return { ok: false, error: 'route_forward_is_vp_only' };
+    }
+    if (!to || typeof to !== 'string') {
+      return { ok: false, error: 'to_required' };
+    }
+    if (typeof text !== 'string' || text.length === 0) {
+      return { ok: false, error: 'text_required' };
+    }
+    if (to === from) {
+      return { ok: false, error: 'self_forward_rejected' };
+    }
+
+    const meta = coordinator.group.getMeta();
+    if (!meta) return { ok: false, error: 'group_not_initialised' };
+
+    // Roster membership — `all` is reserved broadcast sentinel handled by
+    // coordinator; anything else must be a real member so we fail fast with
+    // a VP-friendly error before hitting Coordinator.
+    if (to !== 'all' && !isMember(meta, to)) {
+      return { ok: false, error: 'target_not_in_roster' };
+    }
+
+    // Build the causedBy chain BEFORE constructing the synthetic user-like
+    // message. We don't know the new msgId yet (coordinator mints it on
+    // appendMessage), so we only include the inbound chain + inbound msgId.
+    // The guard runs against the *pre-dispatch* chain; that matches the
+    // spec's intent ("depth of forwards already taken").
+    const chain = extendCausedBy(args.inboundEnvelope || null, null);
+
+    // Loop guard: for broadcast, use 'all' as the target key so one VP
+    // spamming @all still gets throttled even if each cycle hits different
+    // member inboxes.
+    const guardKey = to === 'all' ? 'all' : to;
+    const verdict = guard.check({
+      groupId: meta.id,
+      targetVpId: guardKey,
+      chain,
+    });
+    if (!verdict.ok) {
+      return {
+        ok: false,
+        error: verdict.reason,          // 'chain_depth_exceeded' | 'throttled'
+        detail: verdict.detail || null,
+      };
+    }
+
+    // Synthesize an injection message — coordinator's `ingest` expects the
+    // {from, role, text} shape. We set role='user' ONLY because that's the
+    // code path that triggers @-routing; semantically it is a VP-initiated
+    // injection. The `from` field preserves the real sender vpId, and we
+    // stamp meta.synthetic + meta.injectedBy so downstream auditors can
+    // tell it apart from real user input.
+    //
+    // Why not add a third role to Coordinator? Scope discipline: Coordinator
+    // (334b) owns user vs VP branching. A third branch would force edits
+    // across both 334b and 334d for one hop. Setting role='user' with
+    // synthetic meta keeps the Coordinator API frozen — and `from` still
+    // reflects the real author, which is what the guard keys on anyway.
+    const injectText = to === 'all'
+      ? `@all ${text}`
+      : `@${to} ${text}`;
+
+    const report = coordinator.ingest(
+      {
+        from,                  // real VP id — preserved for provenance
+        role: 'user',          // triggers coordinator dispatch path
+        text: injectText,
+        taskId: args.taskId ?? null,
+        meta: {
+          synthetic: true,
+          injectedBy: 'route_forward',
+          senderVpId: from,
+          reason: args.reason || null,
+          causedBy: chain,
+        },
+      },
+      opts,
+    );
+
+    // Record AFTER Coordinator accepts. If Coordinator produced zero
+    // dispatches (e.g. task.members gate) we still count it as a hit —
+    // the forwarder still tried, and the guard's job is to throttle the
+    // sender's ability to keep trying.
+    guard.record({ groupId: meta.id, targetVpId: guardKey });
+
+    return {
+      ok: true,
+      dispatched: report.dispatched.slice(),
+      report,
+    };
+  }
+
+  return { forward, guard, coordinator };
+}

package/unify/tools/index.js

@@ -43,6 +43,9 @@ import waitAgent from './wait-agent.js';
 import closeAgent from './close-agent.js';
 import listAgents from './list-agents.js';
 
+// --- P1 Routing tools (task-334d) ---
+import routeForward from './route-forward.js';
+
 // --- P1 Task tools ---
 import {
   taskCreate,
@@ -116,6 +119,9 @@ export const allTools = [
   closeAgent,
   listAgents,
 
+  // P1 Routing (task-334d)
+  routeForward,
+
   // P1 Task
   taskCreate,
   taskUpdate,

package/unify/tools/route-forward.js

@@ -0,0 +1,117 @@
+/**
+ * route-forward.js — VP-facing `route_forward` tool (task-334d).
+ *
+ * VPs cannot trigger @-routing by writing @foo into chat text (that's the
+ * user-only coordinator branch from §6). To hand a turn to another VP, the
+ * VP must call this tool.
+ *
+ * Tool contract:
+ *   route_forward({ to, text, reason? }) → status JSON
+ *     - to:     target vpId, OR the literal 'all' for broadcast
+ *     - text:   the message body to relay
+ *     - reason: optional string — why we're forwarding; logged on meta
+ *
+ * Ctx expectations (supplied by RoleInstance Engine wiring):
+ *   ctx.router         — createRouter() instance for the active group
+ *   ctx.senderVpId     — the VP that owns the running turn
+ *   ctx.inboundEnvelope — the envelope currently being processed (loop guard)
+ *   ctx.taskId         — current task scope, if any
+ *   ctx.taskMembers    — optional member allowlist for task-scoped groups
+ *
+ * Return is always a JSON string so the LLM can reason about ok/error. On
+ * failure the tool does NOT throw (that would kill the turn); it returns
+ * `{ ok: false, error }` so the VP can pivot (apologise, retry, ...).
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'RouteForward',
+  description: `Hand this turn off to another VP in the same group.
+
+Use this tool — NOT free-text @mentions — to route a question or task to
+another VP. VP-authored @mentions in chat text are NOT automatically routed
+(the group coordinator only text-routes for user messages); you must call
+RouteForward for the hand-off to take effect.
+
+Arguments:
+  - to (string): target vpId, or the literal "all" to broadcast to every
+    other member of the group (subject to the per-group fan-out cap).
+  - text (string): the message body to send on your behalf.
+  - reason (string, optional): short rationale for the forward, recorded on
+    the message meta for audit / UI display.
+
+Rules:
+  - Forwarding to yourself is rejected (self_forward_rejected).
+  - Forwarding to a non-member is rejected (target_not_in_roster).
+  - Forwards carry a causedBy chain; chains deeper than 10 hops are blocked
+    (chain_depth_exceeded).
+  - A single target may be forwarded to at most 8 times per 5-second window
+    per group (throttled).
+
+Returns JSON: { ok, dispatched?, error?, detail? }.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      to: {
+        type: 'string',
+        description: 'Target vpId, or "all" for broadcast',
+      },
+      text: {
+        type: 'string',
+        description: 'The message body to forward',
+      },
+      reason: {
+        type: 'string',
+        description: 'Optional: short rationale for the forward',
+      },
+    },
+    required: ['to', 'text'],
+  },
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input, ctx = {}) {
+    const { to, text, reason } = input || {};
+    if (!to || typeof to !== 'string') {
+      return JSON.stringify({ ok: false, error: 'to_required' });
+    }
+    if (typeof text !== 'string' || text.length === 0) {
+      return JSON.stringify({ ok: false, error: 'text_required' });
+    }
+    const router = ctx.router;
+    const senderVpId = ctx.senderVpId;
+    if (!router || typeof router.forward !== 'function') {
+      return JSON.stringify({ ok: false, error: 'router_unavailable' });
+    }
+    if (!senderVpId) {
+      return JSON.stringify({ ok: false, error: 'sender_unknown' });
+    }
+
+    const result = router.forward(
+      {
+        from: senderVpId,
+        to,
+        text,
+        reason: reason || null,
+        taskId: ctx.taskId ?? null,
+        inboundEnvelope: ctx.inboundEnvelope ?? null,
+      },
+      { taskMembers: ctx.taskMembers },
+    );
+
+    if (!result.ok) {
+      return JSON.stringify({
+        ok: false,
+        error: result.error,
+        detail: result.detail || null,
+      });
+    }
+    return JSON.stringify({
+      ok: true,
+      dispatched: result.dispatched,
+      broadcast: Boolean(result.report?.broadcast),
+      truncatedAtFanOutCap: Boolean(result.report?.truncatedAtFanOutCap),
+      errors: result.report?.errors || [],
+    });
+  },
+});