@yeaft/webchat-agent 0.1.593 → 0.1.594

package/package.json

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

package/unify/prompts.js

@@ -163,6 +163,8 @@ const RAW_TEMPLATES = {
   // buildRouterPrompt callers will simply omit the section.
   harnessWorkerShape: readTemplate('harness/worker-shape.md', { required: false }),
   harnessRouterShape: readTemplate('harness/router-shape.md', { required: false }),
+  // Phase 3b — coordinator harness rule for inter-VP forwarding.
+  harnessRouterHandoff: readTemplate('harness/router-handoff.md', { required: false }),
 };
 
 /**
@@ -768,6 +770,39 @@ export function buildWorkerPrompt(params = {}) {
   return parts.join('\n\n');
 }
 
+/**
+ * Render the previous turn's router plan as a `## prior_plan` block, so
+ * the router can decide whether to extend it or start fresh
+ * (DESIGN.md §9.15). Returns '' when there is no prior plan to render.
+ *
+ * @param {object|null|undefined} priorPlan
+ * @param {'en'|'zh'} [language='en']
+ * @returns {string}
+ */
+export function renderPriorPlan(priorPlan, language = 'en') {
+  if (!priorPlan || typeof priorPlan !== 'object') return '';
+  const header = language === 'zh' ? '## 上一轮 plan' : '## prior_plan';
+  const lines = [];
+  if (priorPlan.vpId) lines.push(`vpId: ${priorPlan.vpId}`);
+  const fq = priorPlan.forwardQuery;
+  if (fq && (fq.userOriginal || fq.intent)) {
+    if (fq.intent) lines.push(`intent: ${fq.intent}`);
+    if (fq.userOriginal) lines.push(`userOriginal: ${fq.userOriginal}`);
+  }
+  const pre = priorPlan.preselect;
+  if (pre) {
+    if (Array.isArray(pre.memoryPaths) && pre.memoryPaths.length) {
+      lines.push(`memoryPaths: ${pre.memoryPaths.join(', ')}`);
+    }
+    if (Array.isArray(pre.taskIds) && pre.taskIds.length) {
+      lines.push(`taskIds: ${pre.taskIds.join(', ')}`);
+    }
+  }
+  if (priorPlan.thinking) lines.push(`thinking: ${priorPlan.thinking}`);
+  if (!lines.length) return '';
+  return `${header}\n${lines.join('\n')}`;
+}
+
 /**
  * Router prompt entry point (DESIGN.md Phase 1).
  *
@@ -780,12 +815,13 @@ export function buildWorkerPrompt(params = {}) {
  *   language?: 'en'|'zh',
  *   summaries?: {user?: string, group?: string, vp?: string},
  *   routerContext?: string,
+ *   priorPlan?: object|null,
  *   includeShape?: boolean,
  * }} params
  * @returns {string}
  */
 export function buildRouterPrompt(params = {}) {
-  const { language = 'en', summaries, routerContext, includeShape = true } = params;
+  const { language = 'en', summaries, routerContext, priorPlan, includeShape = true } = params;
   const parts = [];
 
   if (includeShape) {
@@ -796,6 +832,9 @@ export function buildRouterPrompt(params = {}) {
   const summaryBlock = renderLayerASummaries(summaries, language);
   if (summaryBlock) parts.push(summaryBlock);
 
+  const priorBlock = renderPriorPlan(priorPlan, language);
+  if (priorBlock) parts.push(priorBlock);
+
   if (typeof routerContext === 'string' && routerContext.trim()) {
     parts.push(routerContext.trim());
   }

package/unify/router/continuity.js

@@ -0,0 +1,108 @@
+/**
+ * router/continuity.js — DESIGN.md §9.15 priorPlan carry-back.
+ *
+ * Phase 3b scope:
+ *   - `attachRouterPlan(message, plan)` — write the plan as `_meta.routerPlan`
+ *     on the assistant message that produced it.
+ *   - `extractPriorPlan(messages, vpId)` — find the most recent assistant
+ *     message belonging to the given VP and return its `_meta.routerPlan`.
+ *   - `stripMetaForWire(messages)` — drop `_meta` before sending to the LLM
+ *     (it's bookkeeping, never model-visible).
+ *
+ * The skip-router heuristic (§9.15 #1) is intentionally NOT implemented in
+ * Phase 3b — DESIGN.md §8 line 391 says "do NOT ship the skip-router
+ * heuristic yet". We just plumb the metadata; the dispatcher can decide.
+ *
+ * Per-VP attribution: an assistant message belongs to a VP when its
+ * `_meta.routerPlan.vpId` matches; we never guess from content. First turn
+ * of a fresh group has no priorPlan — that is the expected cold-start.
+ */
+
+/** @typedef {{
+ *   vpId: string,
+ *   forwardQuery?: { userOriginal?: string, intent?: string },
+ *   preselect?: { memoryPaths?: string[], taskIds?: string[] },
+ *   thinking?: 'high'|'max'|null,
+ *   thinkingReason?: string,
+ * }} RouterPlanLike
+ */
+
+/**
+ * Attach a router plan to an assistant message. Mutates `message` in place
+ * and returns it. We mutate (rather than clone) because the caller is the
+ * engine appending to its own `conversationMessages` array — cloning would
+ * just discard the work.
+ *
+ * Tool messages do not carry plans (no plan attached to a tool result).
+ *
+ * @param {object} message
+ * @param {RouterPlanLike|null|undefined} plan
+ * @returns {object}
+ */
+export function attachRouterPlan(message, plan) {
+  if (!message || typeof message !== 'object') return message;
+  if (message.role !== 'assistant') return message;
+  if (!plan || typeof plan !== 'object' || !plan.vpId) return message;
+  message._meta = message._meta || {};
+  message._meta.routerPlan = {
+    vpId: plan.vpId,
+    forwardQuery: plan.forwardQuery
+      ? {
+        userOriginal: plan.forwardQuery.userOriginal || '',
+        intent: plan.forwardQuery.intent || '',
+      } : undefined,
+    preselect: plan.preselect
+      ? {
+        memoryPaths: Array.isArray(plan.preselect.memoryPaths)
+          ? [...plan.preselect.memoryPaths] : [],
+        taskIds: Array.isArray(plan.preselect.taskIds)
+          ? [...plan.preselect.taskIds] : [],
+      } : undefined,
+    thinking: plan.thinking ?? null,
+    thinkingReason: plan.thinkingReason || '',
+  };
+  return message;
+}
+
+/**
+ * Walk `messages` from the end, return the most recent assistant message's
+ * `_meta.routerPlan` whose `vpId` matches. Returns null if none found —
+ * that's a cold start, not an error.
+ *
+ * @param {object[]} messages
+ * @param {string} vpId
+ * @returns {RouterPlanLike | null}
+ */
+export function extractPriorPlan(messages, vpId) {
+  if (!Array.isArray(messages) || !vpId) return null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (!m || m.role !== 'assistant') continue;
+    const plan = m._meta && m._meta.routerPlan;
+    if (plan && plan.vpId === vpId) return plan;
+  }
+  return null;
+}
+
+/**
+ * Return a copy of the messages array with `_meta` stripped from every
+ * message. The serialisers (anthropic/openai-responses) read this; it is
+ * NEVER part of the wire payload. Cheap because we only shallow-clone the
+ * messages that actually have `_meta`.
+ *
+ * @param {object[]} messages
+ * @returns {object[]}
+ */
+export function stripMetaForWire(messages) {
+  if (!Array.isArray(messages)) return messages;
+  let mutated = false;
+  const out = messages.map(m => {
+    if (m && typeof m === 'object' && '_meta' in m) {
+      mutated = true;
+      const { _meta, ...rest } = m;
+      return rest;
+    }
+    return m;
+  });
+  return mutated ? out : messages;
+}

package/unify/router/thinking.js

@@ -0,0 +1,78 @@
+/**
+ * router/thinking.js — DESIGN.md §9.16 thinking-mode precedence chain.
+ *
+ * Resolves the final `thinking` value the engine should pass to the
+ * adapter, given the four signal sources:
+ *
+ *   1. UI override     (highest)  — submitOptions / topbar selector
+ *   2. Router plan     —           — per-plan thinking field
+ *   3. VP default      —           — vp/<id>/role.md frontmatter
+ *   4. Global default  (lowest)    — config.thinking.default
+ *
+ * Allowed values: `'high' | 'max' | null`. (`null` ⇒ adapter drops the
+ * field; provider-specific normalisation happens at the adapter via
+ * `models.js#normalizeEffort`.)
+ *
+ * Continuity rule (§9.16): when no UI override is in force AND the router
+ * did not change its recommendation versus the prior plan, keep the prior
+ * plan's value. Anthropic prompt cache keys include the thinking field;
+ * unstable values cause prefix re-encoding every turn.
+ *
+ * The `allowRouterEscalate: false` config gate hard-blocks the router
+ * from bumping below→`max`. UI overrides bypass that gate (they're the
+ * user's direct intent, not a heuristic).
+ */
+
+const ALLOWED = new Set([null, 'high', 'max']);
+
+/**
+ * @param {*} v
+ * @returns {'high'|'max'|null}
+ */
+function clean(v) {
+  if (v === undefined) return null;
+  return ALLOWED.has(v) ? v : null;
+}
+
+/**
+ * @param {{
+ *   uiOverride?: 'high'|'max'|null,
+ *   routerPlan?: 'high'|'max'|null,
+ *   priorPlan?: 'high'|'max'|null,
+ *   vpDefault?: 'high'|'max'|null,
+ *   globalDefault?: 'high'|'max'|null,
+ *   allowRouterEscalate?: boolean,
+ * }} signals
+ * @returns {{ value: 'high'|'max'|null, source: 'ui'|'router'|'prior'|'vp'|'global'|'default' }}
+ */
+export function resolveThinking(signals = {}) {
+  const ui = clean(signals.uiOverride);
+  if (ui) return { value: ui, source: 'ui' };
+
+  const router = clean(signals.routerPlan);
+  const prior = clean(signals.priorPlan);
+  const vp = clean(signals.vpDefault);
+  const global_ = clean(signals.globalDefault);
+  const escalateOk = signals.allowRouterEscalate !== false;
+
+  // Continuity: if router agrees with prior or is silent, prefer prior to
+  // keep the cache key stable.
+  if (router && prior && router === prior) {
+    return { value: prior, source: 'prior' };
+  }
+
+  if (router) {
+    // allowRouterEscalate=false hard-blocks router from emitting 'max'
+    // when the baseline is 'high'.
+    const baseline = prior || vp || global_ || 'high';
+    if (!escalateOk && router === 'max' && baseline !== 'max') {
+      return { value: baseline, source: prior ? 'prior' : (vp ? 'vp' : 'global') };
+    }
+    return { value: router, source: 'router' };
+  }
+
+  if (prior) return { value: prior, source: 'prior' };
+  if (vp) return { value: vp, source: 'vp' };
+  if (global_) return { value: global_, source: 'global' };
+  return { value: 'high', source: 'default' };
+}

package/unify/router/vp-planner.js

@@ -280,3 +280,62 @@ export async function runPlansSequential(plans, runOne, opts = {}) {
   }
   return { results, errors };
 }
+
+/**
+ * Parallel fan-out runner (Phase 3.5). Calls `runOne(plan, index)` for each
+ * plan concurrently, with optional `concurrency` cap. Results are returned
+ * in input order regardless of completion order. Errors from `runOne` are
+ * caught per-plan and DO NOT abort siblings (DESIGN.md §9.1 — concurrent
+ * VP turns must be independent).
+ *
+ * NOTE: parallel mode loses the `prior[]` channel that the sequential
+ * runner provides. Callers that need plan N to read plan N-1's output must
+ * use `runPlansSequential`. The dispatcher chooses based on whether the
+ * plans share a `targetTaskId` (parallel-safe) or pipeline data
+ * (sequential-only).
+ *
+ * @param {VpPlan[]} plans
+ * @param {(plan: VpPlan, index: number) => Promise<*>} runOne
+ * @param {{ groupMemberIds?: string[], concurrency?: number }} [opts]
+ * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
+ */
+export async function runPlansParallel(plans, runOne, opts = {}) {
+  if (!Array.isArray(plans)) throw new Error('runPlansParallel: plans array required');
+  if (typeof runOne !== 'function') throw new Error('runPlansParallel: runOne fn required');
+  const memberSet = Array.isArray(opts.groupMemberIds)
+    ? new Set(opts.groupMemberIds) : null;
+  const concurrency = Number.isFinite(opts.concurrency) && opts.concurrency > 0
+    ? Math.floor(opts.concurrency) : Infinity;
+
+  const results = new Array(plans.length);
+  const errors = [];
+  let nextIdx = 0;
+
+  const runSlot = async () => {
+    // Workers pull tasks from a shared queue index — preserves backpressure
+    // when concurrency < plans.length without per-task scheduling overhead.
+    while (true) {
+      const i = nextIdx;
+      nextIdx += 1;
+      if (i >= plans.length) return;
+      const plan = plans[i];
+      if (memberSet && !memberSet.has(plan.vpId)) {
+        results[i] = { index: i, vpId: plan.vpId, skipped: 'not_member' };
+        continue;
+      }
+      try {
+        results[i] = await runOne(plan, i);
+      } catch (err) {
+        errors.push({ index: i, error: err });
+        results[i] = { index: i, vpId: plan.vpId, error: err };
+      }
+    }
+  };
+
+  const workerCount = Math.min(plans.length, concurrency);
+  const workers = [];
+  for (let w = 0; w < workerCount; w += 1) workers.push(runSlot());
+  await Promise.all(workers);
+
+  return { results, errors };
+}

package/unify/templates/harness/router-handoff.md

@@ -0,0 +1,34 @@
+<!-- lang:en -->
+# Harness — Router Handoff
+
+If, while drafting your reply, you realise you are the wrong VP for this
+turn, hand off instead of guessing. Call `route_forward(targetVpId, reason)`
+with a short, actionable reason. The next turn becomes the receiving VP's
+turn with your reason as the inbound envelope — they act with no other
+context from you.
+
+Use this when:
+
+- The user's question is outside your expertise and another VP in the
+  group clearly owns it.
+- Your read of the situation is "this is comms not kernel" / "this is
+  legal not engineering" — name the boundary.
+
+Do NOT use this to dodge hard questions you legitimately own. The router
+already picked you; only forward when the topic genuinely belongs to
+someone else.
+<!-- lang:zh -->
+# Harness — Router 转交
+
+如果你在起草回复时发现本轮应该由其他 VP 来回答，请直接转交，而不是
+强答。调用 `route_forward(targetVpId, reason)` 并给出简短可操作的原因。
+下一轮变为目标 VP 的回合，你给的 reason 即为他们看到的入站信封——他
+们不会读到你的其他上下文。
+
+适用场景：
+
+- 用户的问题超出你的专业范围，群里另一个 VP 显然更合适。
+- 你判断「这是沟通不是内核」/「这是法务不是工程」——说出边界。
+
+不要用它来回避你确实该回答的问题。Router 既然选了你，只有当话题
+确实属于他人时才转交。