@yeaft/webchat-agent 0.1.791 → 0.1.792

package/package.json

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

package/unify/config.js

@@ -42,6 +42,11 @@ const DEFAULTS = {
   // plumb the knob through so the UI can set it).
   unifyMaxConcurrentThreads: 6,
   unifyAutoArchiveIdleDays: 30,
+  // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Mirrors Codex's
+  // `project_doc_max_bytes`. 0 disables the feature (no project-doc
+  // block is injected). Hand-edited values are NOT clamped — we let
+  // power users opt into larger docs at their own context-window risk.
+  projectDocMaxBytes: 32 * 1024,
 };
 
 // ─── config.json reader ─────────────────────────────────────────
@@ -215,6 +220,10 @@ function loadLegacyConfig(dir, overrides) {
     maxOutputTokens: overrides.maxOutputTokens ?? fileConfig.maxOutputTokens ?? DEFAULTS.maxOutputTokens,
     messageTokenBudget: overrides.messageTokenBudget ?? (env.YEAFT_MESSAGE_TOKEN_BUDGET ? parseInt(env.YEAFT_MESSAGE_TOKEN_BUDGET, 10) : null) ?? fileConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? fileConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
+    // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Legacy config
+    // has no field for this, so it always lands on the default unless
+    // explicitly overridden via CLI.
+    projectDocMaxBytes: overrides.projectDocMaxBytes ?? fileConfig.projectDocMaxBytes ?? DEFAULTS.projectDocMaxBytes,
     // task-318: legacy path never had the `unify` section — defaults.
     unify: normaliseUnifySection(null),
     providers: null,
@@ -309,6 +318,11 @@ export function loadConfig(overrides = {}) {
     messageTokenBudget: overrides.messageTokenBudget ?? jsonConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? jsonConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
 
+    // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Set to 0 to
+    // disable the feature entirely. Read from `projectDocMaxBytes` in
+    // ~/.yeaft/config.json or threaded through CLI overrides.
+    projectDocMaxBytes: overrides.projectDocMaxBytes ?? jsonConfig.projectDocMaxBytes ?? DEFAULTS.projectDocMaxBytes,
+
     // task-318: Unify runtime caps. `unify` is a nested section so we
     // don't pollute the flat config namespace used by chat/crew code.
     unify: normaliseUnifySection(jsonConfig.unify),

package/unify/engine.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes } from './groups/pre-flow.js';
+import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './groups/project-doc.js';
 import { shouldConsolidate, partitionMessages } from './memory/consolidate.js';
 import { runCompact as runCompactOrchestrator } from './compact/orchestrator.js';
 import { evaluateCompactTriggers } from './compact/triggers.js';
@@ -323,6 +324,18 @@ export class Engine {
   /** @type {string|null} */
   #abortReason = null;
 
+  /**
+   * Per-engine cache of the resolved CLAUDE.md / AGENTS.md project doc.
+   * Shape: `{ workDir, path, mtimeMs, text } | null`. A non-null record
+   * means "for THIS workDir, the file at `path` with this `mtimeMs`
+   * resolved to `text`" — when the next turn's stat returns the same
+   * `(path, mtimeMs)` tuple, we skip the read entirely. mtime changes
+   * (or a different picked file, e.g. user added AGENTS.md) invalidate
+   * automatically because the `path`/`mtimeMs` comparison fails.
+   * @type {{ workDir: string, path: string, mtimeMs: number, text: string }|null}
+   */
+  #projectDocCache = null;
+
   /**
    * @param {{
    *   adapter: import('./llm/adapter.js').LLMAdapter,
@@ -685,10 +698,11 @@ export class Engine {
    * @param {object} [args.vpPersona]
    * @param {object} [args.activeScope] — DESIGN-PROMPT §3 ④ structured scope summary
    * @param {string} [args.groupAnnouncement]
+   * @param {string} [args.projectDoc] — resolved CLAUDE.md / AGENTS.md text (already truncated)
    * @param {object} [args.taskCtx] — legacy task-context sub-block (optional)
    * @returns {string}
    */
-  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, groupAnnouncement, taskCtx } = {}) {
+  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, groupAnnouncement, projectDoc, taskCtx } = {}) {
     // Get relevant skill content if SkillManager is wired
     let skillContent = '';
     if (this.#skillManager && prompt) {
@@ -708,6 +722,7 @@ export class Engine {
       vpPersona,
       activeScope,
       groupAnnouncement,
+      projectDoc,
       taskCtx,
       // Worker-shape harness is descriptive metadata for human inspection;
       // production prompts skip it to save tokens. Re-enable via env when
@@ -716,6 +731,76 @@ export class Engine {
     });
   }
 
+  /**
+   * Resolve the CLAUDE.md / AGENTS.md project doc text for the current
+   * group's working directory. mtime-cached on the engine so we only
+   * re-read the file when the user actually edited it.
+   *
+   * Cache strategy:
+   *   1. Cheap path: `pickProjectDocFile` (two stats, no read).
+   *   2. If the picked `(path, mtimeMs)` matches the cache → return
+   *      cached text. No disk read, no UTF-8 decode, no truncation work.
+   *   3. Cache miss → call `readProjectDoc` (bounded `readSync` into a
+   *      pre-sized buffer), refresh the cache, return the fresh text.
+   *
+   * Returns '' when:
+   *   - workDir is empty / not a string
+   *   - config.projectDocMaxBytes === 0 (feature disabled)
+   *   - neither CLAUDE.md nor AGENTS.md exists in workDir
+   *   - the picked file is empty after trim
+   *
+   * @param {string|undefined} workDir
+   * @returns {string}
+   */
+  #getProjectDocBlock(workDir) {
+    if (typeof workDir !== 'string' || !workDir.trim()) {
+      this.#projectDocCache = null;
+      return '';
+    }
+    const maxBytes = Number.isFinite(this.#config?.projectDocMaxBytes)
+      ? this.#config.projectDocMaxBytes
+      : DEFAULT_PROJECT_DOC_MAX_BYTES;
+    if (maxBytes === 0) {
+      this.#projectDocCache = null;
+      return '';
+    }
+
+    // Step 1 — stat-only check. Cheap (two `statSync` calls) and lets
+    // us short-circuit the read when the file hasn't moved.
+    const picked = pickProjectDocFile(workDir);
+    if (!picked) {
+      this.#projectDocCache = null;
+      return '';
+    }
+
+    // Step 2 — cache hit? Same workDir, same picked file, same mtime
+    // ⇒ the previously decoded text is still authoritative. Skip the
+    // file read entirely.
+    const cache = this.#projectDocCache;
+    if (
+      cache
+      && cache.workDir === workDir
+      && cache.path === picked.path
+      && cache.mtimeMs === picked.mtimeMs
+    ) {
+      return cache.text;
+    }
+
+    // Step 3 — cache miss. Read + decode, then refresh the cache.
+    const doc = readProjectDoc(workDir, { maxBytes });
+    if (!doc) {
+      this.#projectDocCache = null;
+      return '';
+    }
+    this.#projectDocCache = {
+      workDir,
+      path: doc.path,
+      mtimeMs: doc.mtimeMs,
+      text: doc.text,
+    };
+    return doc.text;
+  }
+
   /**
    * Build the full tool context for Phase 5 tools.
    *
@@ -1037,7 +1122,7 @@ export class Engine {
    *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1096,7 +1181,7 @@ export class Engine {
     const runSignal = abortCtrl.signal;
 
     try {
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted, getCurrentTodos, setCurrentTodos });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -1114,7 +1199,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null }) {
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -1183,12 +1268,15 @@ export class Engine {
       envelope: inboundEnvelope || null,
     };
 
+    const projectDoc = this.#getProjectDocBlock(workDir);
+
     const systemPrompt = this.#buildSystemPrompt({
       prompt,
       memoryInjection,
       vpPersona,
       activeScope,
       groupAnnouncement,
+      projectDoc,
     });
 
     // ─── Compact summary as messages-array head (DESIGN-PROMPT §4.3) ─

package/unify/groups/project-doc.js

@@ -0,0 +1,148 @@
+/**
+ * project-doc.js — Read CLAUDE.md / AGENTS.md from a group's workDir.
+ *
+ * Per-group, the user may park a project-level instructions file in the
+ * group's configured `workDir`. This module is the stateless reader for
+ * those files. The Engine owns the cache (per session, per VP) so that
+ * mtime-driven invalidation can happen without a singleton cache.
+ *
+ * File-selection rule (matches user spec):
+ *   • If both `CLAUDE.md` and `AGENTS.md` exist, the one with the newer
+ *     mtime wins. Tie → CLAUDE.md (deterministic; this is the project's
+ *     own convention).
+ *   • If only one exists, pick it.
+ *   • If neither exists, return null. Caller skips the prompt block.
+ *
+ * Why two filenames? CLAUDE.md is this project's convention; AGENTS.md
+ * is the cross-tool convention adopted by Codex / OpenAI Codex CLI. Both
+ * carry the same kind of payload — long-form project instructions — and
+ * we want users coming from either ecosystem to "just work".
+ *
+ * Size cap. We read up to `maxBytes` and truncate larger files with a
+ * console warning. Default cap is 32 KB (`DEFAULT_PROJECT_DOC_MAX_BYTES`),
+ * mirroring Codex's `project_doc_max_bytes`. Setting the cap to 0 in the
+ * engine config disables the feature entirely (the caller short-circuits
+ * before reaching this module).
+ *
+ * NO module-level cache. The engine holds the cache so a mtime change
+ * between sessions doesn't ride along into a fresh engine instance, and
+ * tests can construct two engines without interfering with each other.
+ */
+
+import { statSync, openSync, readSync, closeSync } from 'fs';
+import { join } from 'path';
+
+/** Filenames probed in `workDir`, in tie-break order (first wins on tie). */
+export const PROJECT_DOC_FILENAMES = ['CLAUDE.md', 'AGENTS.md'];
+
+/** Default max bytes pulled into the prompt block. Matches Codex. */
+export const DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024;
+
+/**
+ * Stat both candidate filenames in `workDir` and return whichever has the
+ * newer mtime, or null when neither exists / workDir is unusable.
+ *
+ * Pure stat — does NOT read file contents. Returns a lightweight stat
+ * record so the caller can compare against a cached `mtimeMs` before
+ * deciding to re-read.
+ *
+ * @param {string} workDir
+ * @returns {{ path: string, mtimeMs: number } | null}
+ */
+export function pickProjectDocFile(workDir) {
+  if (typeof workDir !== 'string' || !workDir.trim()) return null;
+  try {
+    const dirStat = statSync(workDir);
+    if (!dirStat.isDirectory()) return null;
+  } catch {
+    // Non-existent / permission-denied / not a path we can stat.
+    return null;
+  }
+
+  let best = null;
+  for (const name of PROJECT_DOC_FILENAMES) {
+    const path = join(workDir, name);
+    let s;
+    try {
+      s = statSync(path);
+    } catch {
+      // Missing or unreadable; try the next candidate.
+      continue;
+    }
+    if (!s.isFile()) continue;
+    // Strict-greater so ties favor the order in PROJECT_DOC_FILENAMES.
+    if (!best || s.mtimeMs > best.mtimeMs) {
+      best = { path, mtimeMs: s.mtimeMs };
+    }
+  }
+  return best;
+}
+
+/**
+ * Read the picked project-doc file. Returns null when nothing is
+ * eligible (no workDir, no file, empty contents after trim).
+ *
+ * Bounded I/O. We allocate `maxBytes + 1` bytes and `readSync` once —
+ * never letting a runaway file balloon the agent's heap. The extra
+ * byte tells us whether the file was actually larger (so we know to
+ * warn about truncation).
+ *
+ * Codepoint-safe truncation. When we cut mid-byte inside a multi-byte
+ * UTF-8 sequence (very likely for `zh-CN` docs), we walk back to the
+ * last codepoint boundary before decoding, so the model sees clean
+ * text instead of a trailing `U+FFFD` replacement character.
+ *
+ * @param {string} workDir
+ * @param {{ maxBytes?: number }} [opts]
+ * @returns {{ path: string, mtimeMs: number, text: string } | null}
+ */
+export function readProjectDoc(workDir, opts = {}) {
+  const maxBytes = Number.isFinite(opts.maxBytes) && opts.maxBytes >= 0
+    ? opts.maxBytes
+    : DEFAULT_PROJECT_DOC_MAX_BYTES;
+  if (maxBytes === 0) return null;
+
+  const picked = pickProjectDocFile(workDir);
+  if (!picked) return null;
+
+  // Allocate one extra byte so a `bytesRead === maxBytes + 1` tells us
+  // there's more content beyond the cap — i.e. the file was truncated.
+  const cap = maxBytes + 1;
+  const buffer = Buffer.allocUnsafe(cap);
+  let fd;
+  let bytesRead = 0;
+  try {
+    fd = openSync(picked.path, 'r');
+    bytesRead = readSync(fd, buffer, 0, cap, 0);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+  }
+
+  let useBytes = bytesRead;
+  const truncated = bytesRead > maxBytes;
+  if (truncated) {
+    useBytes = maxBytes;
+    // Walk back into the buffer until the cut isn't sitting in the
+    // middle of a multi-byte UTF-8 sequence. Each continuation byte
+    // matches the pattern `10xxxxxx` (0x80–0xBF). We scan back at most
+    // 3 bytes — UTF-8 codepoints are ≤ 4 bytes total.
+    let scan = 0;
+    while (scan < 3 && useBytes > 0 && (buffer[useBytes] & 0xC0) === 0x80) {
+      useBytes -= 1;
+      scan += 1;
+    }
+  }
+
+  const text = buffer.toString('utf8', 0, useBytes).trim();
+  if (truncated) {
+    console.warn(
+      `[unify/project-doc] ${picked.path} exceeds ${maxBytes} bytes — truncated.`,
+    );
+  }
+  if (!text) return null;
+  return { path: picked.path, mtimeMs: picked.mtimeMs, text };
+}

package/unify/prompts.js

@@ -195,6 +195,12 @@ const PROMPTS = {
     // DESIGN-PROMPT §3 ④ — Active Scope header
     activeScopeHeader: '## active_scope',
     groupAnnouncementHeader: '[Group Announcement]',
+    // Project-doc (CLAUDE.md / AGENTS.md) header + one-liner intro. Both
+    // filenames are recognized: CLAUDE.md is this project's convention,
+    // AGENTS.md is the cross-tool convention (Codex / OpenAI Codex CLI).
+    projectDocHeader: '[Project Doc]',
+    projectDocIntro:
+      'The user keeps project-level instructions and context in `CLAUDE.md` or `AGENTS.md` at the group\'s working directory. Treat the content below as authoritative project context — coding conventions, task guidance, workflow rules, etc.',
     vpPersonaIntro: (name, role) =>
       `You ARE **${name}**${role ? ` (${role})` : ''}. Speak in the first person as ${name}; do not refer to yourself as "Yeaft" or as a generic AI assistant. The text below is your identity, expertise, and decision style.`,
   },
@@ -206,6 +212,10 @@ const PROMPTS = {
     // DESIGN-PROMPT §3 ④ — Active Scope header
     activeScopeHeader: '## active_scope',
     groupAnnouncementHeader: '[群组公告]',
+    // 项目文档块：CLAUDE.md / AGENTS.md（与 Codex 通用命名兼容）。
+    projectDocHeader: '[项目文档]',
+    projectDocIntro:
+      '用户把项目级的说明和上下文记录在群组工作目录下的 `CLAUDE.md` 或 `AGENTS.md` 中。下面的内容是权威的项目上下文 —— 编码规范、任务指导、工作流约定等，请遵循它来工作。',
     vpPersonaIntro: (name, role) =>
       `你就是 **${name}**${role ? `（${role}）` : ''}。请以 ${name} 的第一人称发言；不要自称 "Yeaft" 或泛指的 AI 助手。下面的文字是你的身份、专业方向与判断风格。`,
   },
@@ -271,6 +281,7 @@ export function normalizePromptLanguage(language) {
  *   activeScope?: object,
  *   vpPersona?: object,
  *   groupAnnouncement?: string,
+ *   projectDoc?: string,
  * }} params
  * @returns {string}
  */
@@ -283,6 +294,7 @@ export function buildSystemPrompt({
   activeScope,
   vpPersona,
   groupAnnouncement = '',
+  projectDoc = '',
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
   const effectiveLang = normalizePromptLanguage(language);
@@ -310,6 +322,21 @@ export function buildSystemPrompt({
     }
   }
 
+  // ─── 1.4  Project Doc (CLAUDE.md / AGENTS.md from group workDir) ───
+  // The group's working-directory may contain a project-level
+  // instructions file. The engine resolves "newest of CLAUDE.md vs
+  // AGENTS.md by mtime" and threads the resulting text through here.
+  // Empty/whitespace = no block emitted. Sits ABOVE the announcement
+  // because user-authored project files are higher signal than the
+  // group-level announcement (which is typically a short rule).
+  const docText = (typeof projectDoc === 'string') ? projectDoc.trim() : '';
+  if (docText) {
+    const docHeader = lang.projectDocHeader || '[Project Doc]';
+    const docIntro = lang.projectDocIntro || '';
+    const introLine = docIntro ? `${docIntro}\n\n` : '';
+    parts.push(`${docHeader}\n${introLine}${docText}`);
+  }
+
   // ─── 1.5  Group Announcement (CLAUDE.md-style shared prefix) ───
   // When a group has set an announcement, every VP in the group sees it
   // near the top of the system prompt — before tools, memory, mode-specific

package/unify/web-bridge.js

@@ -1988,6 +1988,13 @@ export function buildVpQueryOpts({ vpId, groupCoordinator, groupId, envelope })
   if (groupMeta && typeof groupMeta.announcement === 'string') {
     out.groupAnnouncement = groupMeta.announcement;
   }
+  // Surface the group's configured working directory so the engine can
+  // resolve CLAUDE.md / AGENTS.md at that path and inject it as a
+  // [Project Doc] block above the announcement. Groups with no workDir
+  // skip the block silently (matches the announcement contract).
+  if (groupMeta && typeof groupMeta.workDir === 'string' && groupMeta.workDir.trim()) {
+    out.workDir = groupMeta.workDir.trim();
+  }
   try {
     const vp = readVp(resolvedVpId);
     if (vp) {