@yeaft/webchat-agent 0.1.591 → 0.1.592

package/package.json

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

package/unify/llm/chat-completions.js

@@ -45,6 +45,31 @@ function thinkingV1Enabled() {
   return process.env.UNIFY_THINKING_V1 === '1';
 }
 
+/**
+ * task-DESIGN-v4: Chat Completions adapter is deprecated in favour of
+ * `openai-responses.js` (Responses API) for OpenAI-protocol providers and
+ * `anthropic.js` for Anthropic. This warning fires once per process the
+ * first time the adapter is instantiated, unless UNIFY_SUPPRESS_DEPRECATION=1.
+ * Removal is scheduled for Phase 7 of the multi-VP redesign — see
+ * `agent/unify/DESIGN.md` § "Migration Plan".
+ */
+let _chatCompletionsDeprecationWarned = false;
+function warnChatCompletionsDeprecated() {
+  if (_chatCompletionsDeprecationWarned) return;
+  if (process.env.UNIFY_SUPPRESS_DEPRECATION === '1') {
+    _chatCompletionsDeprecationWarned = true;
+    return;
+  }
+  _chatCompletionsDeprecationWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[unify] ChatCompletionsAdapter is deprecated. Migrate OpenAI-protocol '
+    + 'providers to the Responses API (set provider.protocol="openai-responses"). '
+    + 'This adapter will be removed in a future release. Set '
+    + 'UNIFY_SUPPRESS_DEPRECATION=1 to silence this warning.'
+  );
+}
+
 /**
  * Check if a model ID is an OpenAI model that supports max_completion_tokens.
  * OpenAI introduced max_completion_tokens with o1 and made it standard for
@@ -79,6 +104,7 @@ export class ChatCompletionsAdapter extends LLMAdapter {
     super({ apiKey, baseUrl });
     this.#apiKey = apiKey;
     this.#baseUrl = baseUrl.replace(/\/+$/, ''); // strip trailing slash
+    warnChatCompletionsDeprecated();
   }
 
   /** Expose baseUrl for testing. */

package/unify/llm/openai-responses.js

@@ -33,9 +33,34 @@ import {
   LLMServerError,
   LLMAbortError,
 } from './adapter.js';
+import {
+  normalizeEffort,
+  getThinkingCapability,
+} from '../models.js';
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 
+/**
+ * Feature-flag accessor mirroring anthropic.js. UNIFY_THINKING_V1 is OFF by
+ * default; set env to '1' to enable thinking-mode field translation. Read
+ * lazily so tests can flip the flag between calls.
+ */
+function thinkingV1Enabled() {
+  return process.env.UNIFY_THINKING_V1 === '1';
+}
+
+/**
+ * Translate a normalised effort ('low'|'medium'|'high'|'max') into the value
+ * accepted by the OpenAI Responses `reasoning.effort` field. Responses today
+ * accepts 'low'|'medium'|'high' — 'max' degrades to 'high' to match the
+ * registry's normaliseEffort downgrade rule.
+ */
+function effortForResponses(effort) {
+  if (!effort) return null;
+  if (effort === 'max') return 'high';
+  return effort;
+}
+
 export class OpenAIResponsesAdapter extends LLMAdapter {
   #apiKey;
   #baseUrl;
@@ -200,9 +225,9 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
   // ─── Streaming ──────────────────────────────────────────
 
   /**
-   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, extraBody?: object, signal?: AbortSignal }} params
+   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, effort?: 'low'|'medium'|'high'|'max', extraBody?: object, signal?: AbortSignal }} params
    */
-  async *stream({ model, system, messages, tools, maxTokens = 16384, extraBody, signal }) {
+  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, extraBody, signal }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -214,6 +239,20 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
     if (system) body.instructions = system;
     const translatedTools = this.#translateTools(tools);
     if (translatedTools) body.tools = translatedTools;
+
+    // Inject Responses-API thinking-mode field. Mirrors anthropic.js gating:
+    // feature flag must be on, effort must be a known value, and the model's
+    // registry entry must declare thinkingProtocol === 'openai-reasoning'.
+    // Unknown / unsupported models silently drop the field.
+    const normEffort = normalizeEffort(effort);
+    if (thinkingV1Enabled() && normEffort) {
+      const cap = getThinkingCapability(model);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+        const wireEffort = effortForResponses(normEffort);
+        if (wireEffort) body.reasoning = { effort: wireEffort };
+      }
+    }
+
     if (extraBody) Object.assign(body, extraBody);
 
     let response;
@@ -375,7 +414,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
 
   // ─── Non-streaming call() ───────────────────────────────
 
-  async call({ model, system, messages, maxTokens = 4096, extraBody, signal }) {
+  async call({ model, system, messages, maxTokens = 4096, effort, extraBody, signal }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -384,6 +423,17 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
       max_output_tokens: maxTokens,
     };
     if (system) body.instructions = system;
+
+    // Mirror stream()'s thinking injection for non-streaming side queries.
+    const normEffort = normalizeEffort(effort);
+    if (thinkingV1Enabled() && normEffort) {
+      const cap = getThinkingCapability(model);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+        const wireEffort = effortForResponses(normEffort);
+        if (wireEffort) body.reasoning = { effort: wireEffort };
+      }
+    }
+
     if (extraBody) Object.assign(body, extraBody);
 
     let response;

package/unify/prompts.js

@@ -158,6 +158,11 @@ const RAW_TEMPLATES = {
   modeUnified: readTemplate('mode-unified.md'),
   modeDream: readTemplate('mode-dream.md'),
   toolGuidance: readTemplate('tool-guidance.md'),
+  // Phase 1 — DESIGN.md "Migration Plan" harness fragments. Optional so
+  // older deployments without the templates still boot; buildWorkerPrompt /
+  // buildRouterPrompt callers will simply omit the section.
+  harnessWorkerShape: readTemplate('harness/worker-shape.md', { required: false }),
+  harnessRouterShape: readTemplate('harness/router-shape.md', { required: false }),
 };
 
 /**
@@ -637,3 +642,164 @@ function renderCoreMemory(coreMemory, lang, memoryTraceAvailable) {
   }
   return lines.join('\n');
 }
+
+// ─── Phase 1: Worker / Router prompt splits ──────────────────────
+//
+// DESIGN.md (multi-VP redesign) describes two distinct prompt shapes:
+//
+//   • Worker prompt — what a VP sees when it executes a turn. Layered as
+//     A (identity + summaries) / B (router-preselected memory) / C (task
+//     scope) / D (turn scope).
+//   • Router prompt — what the per-VP Router sees before it decides
+//     plans[]. Identity-summary layer + recent group state, no task /
+//     turn-scope detail.
+//
+// To stay backwards-compatible with existing callers we KEEP
+// `buildSystemPrompt` and treat the two new entry points as thin wrappers
+// that:
+//   1) compose Layer-A summaries (user / group / vp) into the right
+//      headed sections, and
+//   2) prepend the matching harness/*-shape.md fragment when present.
+//
+// Subsequent phases will migrate engine.js / router.js to these entry
+// points and start filling Layers B / C with the new memory tree. For
+// now they exist primarily so tests can pin the contract.
+
+const LAYER_A_HEADERS = {
+  en: {
+    user: '## summary_user',
+    group: '## summary_group',
+    vp: '## summary_vp',
+  },
+  zh: {
+    user: '## 用户总结',
+    group: '## 群组总结',
+    vp: '## VP 总结',
+  },
+};
+
+/**
+ * Render Layer A's three rolling summaries (user / group / vp). Each is
+ * optional; missing or empty strings are skipped. Headers follow the
+ * `## summary_<scope>` convention so Layer-B/C/D headers don't collide.
+ *
+ * @param {{user?: string, group?: string, vp?: string}} summaries
+ * @param {'en'|'zh'} language
+ * @returns {string} concatenated block ('' when nothing to render)
+ */
+export function renderLayerASummaries(summaries, language = 'en') {
+  if (!summaries || typeof summaries !== 'object') return '';
+  const headers = LAYER_A_HEADERS[language] || LAYER_A_HEADERS.en;
+  const out = [];
+  for (const key of ['user', 'group', 'vp']) {
+    const body = typeof summaries[key] === 'string' ? summaries[key].trim() : '';
+    if (!body) continue;
+    out.push(`${headers[key]}\n${body}`);
+  }
+  return out.join('\n\n');
+}
+
+/**
+ * Worker prompt entry point (DESIGN.md Phase 1).
+ *
+ * Layered output:
+ *   harness/worker-shape   — what each layer means (optional fragment)
+ *   Layer A — buildSystemPrompt(...) output (identity + persona + Layer-A
+ *             summaries via `summaries`)
+ *   Layer B — `preselectedMemory` block (router-supplied)
+ *   Layer C — `taskScope` block (active task summary + related-task window)
+ *   Layer D — `turnScope` block (inbound envelope, in-flight turn notes)
+ *
+ * Layers B/C/D are passed in as already-rendered strings so this builder
+ * stays free of memory-store / task-store IO. Phase 2/3 will provide the
+ * real renderers; for now any caller can stub them.
+ *
+ * @param {{
+ *   language?: 'en'|'zh',
+ *   summaries?: {user?: string, group?: string, vp?: string},
+ *   preselectedMemory?: string,
+ *   taskScope?: string,
+ *   turnScope?: string,
+ *   includeShape?: boolean,
+ *   ...rest: import('./prompts.js').buildSystemPrompt
+ * }} params
+ * @returns {string}
+ */
+export function buildWorkerPrompt(params = {}) {
+  const {
+    language = 'en',
+    summaries,
+    preselectedMemory,
+    taskScope,
+    turnScope,
+    includeShape = true,
+    ...rest
+  } = params;
+
+  const parts = [];
+
+  // Optional harness — describes the layered shape.
+  if (includeShape) {
+    const shape = getTemplate('harnessWorkerShape', language);
+    if (shape) parts.push(shape);
+  }
+
+  // Layer A — base + persona + summaries.
+  const baseBlock = buildSystemPrompt({ ...rest, language });
+  if (baseBlock) parts.push(baseBlock);
+  const summaryBlock = renderLayerASummaries(summaries, language);
+  if (summaryBlock) parts.push(summaryBlock);
+
+  // Layer B — router-preselected memory entries (rendered upstream).
+  if (typeof preselectedMemory === 'string' && preselectedMemory.trim()) {
+    parts.push(preselectedMemory.trim());
+  }
+
+  // Layer C — task scope.
+  if (typeof taskScope === 'string' && taskScope.trim()) {
+    parts.push(taskScope.trim());
+  }
+
+  // Layer D — turn scope (inbound envelope, in-flight turn notes).
+  if (typeof turnScope === 'string' && turnScope.trim()) {
+    parts.push(turnScope.trim());
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Router prompt entry point (DESIGN.md Phase 1).
+ *
+ * The Router sees identity context (no persona — it speaks as a routing
+ * brain, not as any specific VP), the three Layer-A summaries, and a
+ * `routerContext` block prepared upstream (group roster, recent turns,
+ * pending tasks). Output schema is enforced by the harness fragment.
+ *
+ * @param {{
+ *   language?: 'en'|'zh',
+ *   summaries?: {user?: string, group?: string, vp?: string},
+ *   routerContext?: string,
+ *   includeShape?: boolean,
+ * }} params
+ * @returns {string}
+ */
+export function buildRouterPrompt(params = {}) {
+  const { language = 'en', summaries, routerContext, includeShape = true } = params;
+  const parts = [];
+
+  if (includeShape) {
+    const shape = getTemplate('harnessRouterShape', language);
+    if (shape) parts.push(shape);
+  }
+
+  const summaryBlock = renderLayerASummaries(summaries, language);
+  if (summaryBlock) parts.push(summaryBlock);
+
+  if (typeof routerContext === 'string' && routerContext.trim()) {
+    parts.push(routerContext.trim());
+  }
+
+  return parts.join('\n\n');
+}
+

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

@@ -0,0 +1,49 @@
+<!-- lang:en -->
+# Prompt Shape (Router)
+
+You are the per-VP Router. You see the group's roster, summaries, recent
+turns, and the latest user message. You return a JSON `plans[]` array — one
+plan per VP that should act this turn, in execution order.
+
+Each plan contains:
+
+- `vpId` — which VP runs.
+- `forwardQuery` — `{ userOriginal, intent }`. `userOriginal` is the
+  verbatim user text; `intent` is a one-line gloss in third person. Do not
+  rewrite the user's words; the worker will read both.
+- `preselect` — `{ memoryPaths[], taskIds[] }`. Memory paths are
+  scope-prefixed (`user/`, `groups/<id>/`, `vp/<id>/`, `tasks/<id>/`).
+- `thinking` — `null | "high" | "max"`. Set when the turn warrants
+  deeper reasoning; leave `null` to use the VP / global default.
+- `thinkingReason` — short justification when `thinking` is non-null.
+
+Hard rules:
+- Never include `vp/<other>/` paths in `preselect.memoryPaths`. Cross-VP
+  private memory is hard-blocked.
+- Plans run sequentially in the order returned. Treat ordering as load
+  bearing; the second plan can read the first plan's output.
+- If no VP needs to act, return `{"plans": []}`.
+<!-- lang:zh -->
+# Prompt 结构（Router）
+
+你是当前群组的 Router。你能看到群成员、总结、最近的回合，以及最新的用户
+消息。你返回一个 JSON `plans[]` 数组——每个需要发言的 VP 一个 plan，按
+执行顺序排列。
+
+每个 plan 包含：
+
+- `vpId`：要执行的 VP。
+- `forwardQuery`：`{ userOriginal, intent }`。`userOriginal` 是用户的
+  原话；`intent` 是用第三人称写的一行意图说明。不要改写用户原话，Worker
+  会同时看到两者。
+- `preselect`：`{ memoryPaths[], taskIds[] }`。memoryPaths 必须带 scope
+  前缀（`user/`、`groups/<id>/`、`vp/<id>/`、`tasks/<id>/`）。
+- `thinking`：`null | "high" | "max"`。需要深度推理时设置，否则保持 null
+  使用 VP / 全局默认。
+- `thinkingReason`：当 `thinking` 非空时的简短理由。
+
+硬规则：
+- `preselect.memoryPaths` 不允许包含 `vp/<其他 VP>/`。跨 VP 私有记忆硬
+  屏蔽。
+- plans 按返回顺序串行执行；后一个 plan 可以读到前一个 plan 的输出。
+- 如果本轮无需任何 VP 发言，返回 `{"plans": []}`。

package/unify/templates/harness/worker-shape.md

@@ -0,0 +1,35 @@
+<!-- lang:en -->
+# Prompt Shape (Worker)
+
+You are a Worker VP turn. Your prompt is built from four layers, in order:
+
+- **Layer A — Identity & Context**: who you are (VP persona) plus the three
+  rolling summaries (user / group / vp). Slow-changing; updated by the
+  hourly Dream pass.
+- **Layer B — Pre-selected Memory**: a small set of memory entries the
+  Router decided are relevant for this turn. Treat these as authoritative
+  context; do not re-fetch unless something is missing.
+- **Layer C — Task Scope**: the active task summary and a short window of
+  related task threads. Empty when the turn has no task binding.
+- **Layer D — Turn Scope**: the in-flight messages, tool traces, and any
+  inbound envelope (a forwarded handoff from another VP).
+
+When information is missing, prefer to ask via tools rather than fabricating
+it. When in doubt about scope, the order of trust is: turn → task →
+preselected memory → identity summary.
+<!-- lang:zh -->
+# Prompt 结构（Worker）
+
+你是一个 Worker VP 的回合。Prompt 由四层组成，自上而下：
+
+- **A 层 · 身份与背景**：你的 VP 人设，以及三段缓慢更新的总结（用户 /
+  群组 / VP）。由每小时一次的 Dream 维护。
+- **B 层 · 路由预选记忆**：Router 判定与本轮相关的少量记忆条目，视为权威
+  上下文，缺失时再去取。
+- **C 层 · 任务范围**：当前任务的 summary，以及最近的相关任务窗口。无
+  任务绑定时该层为空。
+- **D 层 · 当前回合**：本轮的消息、工具调用 trace，以及（如有）从其他
+  VP 转交而来的 inbound envelope。
+
+信息缺失时优先用工具询问，不要编造。判定信息可信度的顺序：当前回合 >
+任务范围 > 预选记忆 > 身份总结。