@yeaft/webchat-agent 1.0.308 → 1.0.310

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.308",
+  "version": "1.0.310",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -1147,13 +1147,14 @@ export class Engine {
    * @param {object} [args.vpPersona]
    * @param {object} [args.activeScope] — DESIGN-PROMPT §3 ④ structured scope summary
    * @param {string} [args.sessionAnnouncement]
+   * @param {string} [args.projectInstruction] — server-managed instruction shared by Project Sessions
    * @param {string} [args.workCenterInstructions] — frozen Agent-level Work Center policy
    * @param {string} [args.projectDoc] — resolved CLAUDE.md / AGENTS.md text (already truncated)
    * @param {object} [args.taskCtx] — legacy task-context sub-block (optional)
    * @param {string} [args.explicitSkillName] — leading /skill:<name> command, if present
    * @returns {string}
    */
-  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, workCenterInstructions, projectDoc, taskCtx, activeTasks, explicitSkillName, resolvedSkillContent = null } = {}) {
+  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, projectInstruction, workCenterInstructions, projectDoc, taskCtx, activeTasks, explicitSkillName, resolvedSkillContent = null } = {}) {
     // Skill selection is normally resolved once by #runQuery so the prompt and
     // emitted protocol events describe the exact same skills. Keep the local
     // fallback for internal callers that do not need selection events.
@@ -1180,6 +1181,7 @@ export class Engine {
       vpPersona,
       activeScope,
       sessionAnnouncement,
+      projectInstruction,
       workCenterInstructions,
       projectDoc,
       runtimePlatform: getRuntimePlatformInfo(),
@@ -1351,6 +1353,7 @@ export class Engine {
         adapter: this.#adapter,
         trace: this.#trace,
         config: this.#config,
+        memoryIndex: this.#memoryIndex,
         parentToolRegistry: this.#toolRegistry,
         skillManager: this.#skillManager,
         mcpManager: this.#mcpManager,
@@ -1363,6 +1366,9 @@ export class Engine {
         projectSessionIds: Array.isArray(vpCtx?.projectSessionIds)
           ? vpCtx.projectSessionIds.slice()
           : [],
+        projectInstruction: typeof vpCtx?.projectInstruction === 'string'
+          ? vpCtx.projectInstruction
+          : '',
         parentThreadId: vpCtx?.threadId || this.#currentThreadId || MAIN_THREAD_ID,
         onEvent: this.#subAgentEventSink || null,
         language: this.#config?.language || 'en',
@@ -1859,7 +1865,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, sessionId, sessionMembers, projectSessionIds = null, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds = null, projectInstruction = '', sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1936,7 +1942,7 @@ export class Engine {
     };
     try {
       this.#currentThreadId = threadId || MAIN_THREAD_ID;
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts: effectivePromptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds, sessionTopics, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, askUser, threadId: this.#currentThreadId, vpTurnId, drainPendingUserMessages, prepareProviderRequest, startProviderRequest, finishProviderRequest, failProviderRequest, closePendingUserInput, collabToolPolicy: effectiveCollabToolPolicy, explicitSkillName: parsedSkill.skillName, retryLifecycle });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts: effectivePromptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds, projectInstruction, sessionTopics, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted, getCurrentTodos, setCurrentTodos, askUser, threadId: this.#currentThreadId, vpTurnId, drainPendingUserMessages, prepareProviderRequest, startProviderRequest, finishProviderRequest, failProviderRequest, closePendingUserInput, collabToolPolicy: effectiveCollabToolPolicy, explicitSkillName: parsedSkill.skillName, retryLifecycle });
     } finally {
       // Closing the async generator at a visible retry boundary means the
       // continuation never reached a provider. Keep it out of history and
@@ -1984,7 +1990,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, sessionId, sessionMembers, projectSessionIds = null, sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null, explicitSkillName = null, retryLifecycle }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds = null, projectInstruction = '', sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null, explicitSkillName = null, retryLifecycle }) {
 
     const effectiveCollabToolPolicy = collabToolPolicy === COLLAB_TOOL_POLICY.SINGLE_VP || collabToolPolicy === COLLAB_TOOL_POLICY.MULTI_VP
       ? collabToolPolicy
@@ -2182,6 +2188,7 @@ export class Engine {
       vpPersona,
       activeScope,
       sessionAnnouncement,
+      projectInstruction,
       workCenterInstructions,
       projectDoc,
       activeTasks,
@@ -3582,6 +3589,7 @@ export class Engine {
         senderVpId,
         sessionId: runtimeSessionId,
         projectSessionIds,
+        projectInstruction,
         threadId: runtimeThreadId,
         inboundEnvelope,
         taskId,

package/yeaft/projects/store.js

@@ -37,6 +37,7 @@ function normalizeProject(row, index = 0) {
   return {
     id: row.id,
     name,
+    instruction: typeof row.instruction === 'string' ? row.instruction.trim() : '',
     sessionIds: normalizeSessionIds(row.sessionIds),
     sortOrder: Number.isFinite(row.sortOrder) ? row.sortOrder : index,
     createdAt: typeof row.createdAt === 'string' ? row.createdAt : '',
@@ -92,6 +93,7 @@ export function createProject(yeaftDir, name) {
   const project = {
     id: `project-${randomUUID().slice(0, 8)}`,
     name: requireName(name),
+    instruction: '',
     sessionIds: [],
     sortOrder: projects.length,
     createdAt: now,
@@ -110,6 +112,22 @@ export function renameProject(yeaftDir, projectId, name) {
   return project;
 }
 
+export function updateProjectInstruction(yeaftDir, projectId, instruction) {
+  if (typeof instruction !== 'string') {
+    throw new ProjectStoreError('invalid_instruction', 'Project instruction must be a string');
+  }
+  const nextInstruction = instruction.trim();
+  if (nextInstruction.length > 20_000) {
+    throw new ProjectStoreError('instruction_too_long', 'Project instruction must not exceed 20000 characters');
+  }
+  const projects = loadProjects(yeaftDir);
+  const project = requireProject(projects, projectId);
+  project.instruction = nextInstruction;
+  project.updatedAt = new Date().toISOString();
+  saveProjects(yeaftDir, projects);
+  return project;
+}
+
 export function deleteProject(yeaftDir, projectId) {
   const projects = loadProjects(yeaftDir);
   requireProject(projects, projectId);

package/yeaft/prompts.js

@@ -204,6 +204,8 @@ const PROMPTS = {
     activeScopeEnvelopeLabel: 'Handoff',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[Session Announcement]',
+    projectInstructionHeader: '[Project Instruction]',
+    projectInstructionIntro: 'This server-managed instruction applies to every Session in the current Project.',
     workCenterInstructionsHeader: '[Work Center Agent Instructions]',
     workCenterInstructionsIntro: 'These Agent-level instructions apply to every Action in this WorkItem. Follow them unless they conflict with system/tool safety rules, the authoritative project document, or the WorkItem contract.',
     // Project-doc (CLAUDE.md / AGENTS.md) header + one-liner intro. Both
@@ -226,6 +228,8 @@ const PROMPTS = {
     activeScopeEnvelopeLabel: '转交消息',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[会话公告]',
+    projectInstructionHeader: '[Project 指令]',
+    projectInstructionIntro: '这是服务器管理的 Project 级指令，适用于当前 Project 内的所有 Session。',
     workCenterInstructionsHeader: '[Work Center Agent 指令]',
     workCenterInstructionsIntro: '这些 Agent 级指令作用于当前 Work Item 的每个 Action。除非与系统/工具安全规则、权威项目文档或 Work Item 契约冲突，否则必须遵循。',
     // 项目文档块：CLAUDE.md / AGENTS.md（与 Codex 通用命名兼容）。
@@ -297,6 +301,7 @@ export function normalizePromptLanguage(language) {
  *   activeScope?: object,
  *   vpPersona?: object,
  *   sessionAnnouncement?: string,
+ *   projectInstruction?: string,
  *   workCenterInstructions?: string,
  *   projectDoc?: string,
  * }} params
@@ -311,6 +316,7 @@ export function buildSystemPrompt({
   activeScope,
   vpPersona,
   sessionAnnouncement = '',
+  projectInstruction = '',
   workCenterInstructions = '',
   projectDoc = '',
   runtimePlatform,
@@ -357,6 +363,13 @@ export function buildSystemPrompt({
     parts.push(`${docHeader}\n${introLine}${docText}`);
   }
 
+  const projectInstructionText = typeof projectInstruction === 'string' ? projectInstruction.trim() : '';
+  if (projectInstructionText) {
+    const header = lang.projectInstructionHeader || '[Project Instruction]';
+    const intro = lang.projectInstructionIntro || '';
+    parts.push(`${header}\n${intro ? `${intro}\n\n` : ''}${projectInstructionText}`);
+  }
+
   // ─── 1.5  Session Announcement (CLAUDE.md-style shared prefix) ───
   // When a session has set an announcement, every VP in the session sees it
   // near the top of the system prompt — before tools, memory, mode-specific

package/yeaft/sub-agent/prompt-queue.js

@@ -0,0 +1,22 @@
+/**
+ * Queue a sub-agent continuation with the Project context that is authoritative
+ * for the parent turn which submitted it. Keeping the snapshot on the queue
+ * entry preserves ordering when multiple continuations are submitted before
+ * the child consumes them. Empty values are an explicit Project-context clear.
+ *
+ * @param {object} agent
+ * @param {string} prompt
+ * @param {{ projectSessionIds?: string[], projectInstruction?: string }} projectContext
+ */
+export function enqueueSubAgentPrompt(agent, prompt, projectContext = {}) {
+  if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
+  agent.pendingPrompts.push({
+    prompt,
+    projectSessionIds: Array.isArray(projectContext.projectSessionIds)
+      ? projectContext.projectSessionIds.slice()
+      : [],
+    projectInstruction: typeof projectContext.projectInstruction === 'string'
+      ? projectContext.projectInstruction
+      : '',
+  });
+}

package/yeaft/sub-agent/runner.js

@@ -114,6 +114,7 @@ export function isRestrictedToolName(name) {
  *   trace: object,
  *   config: object,
  *   conversationStore?: object,
+ *   memoryIndex?: object,
  *   memoryStore?: object,
  *   memoryShardStore?: object,
  *   parentToolRegistry?: ToolRegistry,
@@ -124,6 +125,7 @@ export function isRestrictedToolName(name) {
  *   parentVpId?: string,
  *   parentSessionId?: string|null,
  *   projectSessionIds?: string[],
+ *   projectInstruction?: string,
  *   parentThreadId?: string|null,
  *   parentVpPersona?: object,
  *   toolStats?: object,
@@ -152,6 +154,7 @@ export function startSubAgent(agent, deps = {}) {
       trace: deps.trace,
       config: { ...deps.config, _readOnly: true },
       conversationStore: null,
+      memoryIndex: deps.memoryIndex || null,
       memoryStore: deps.memoryStore || null,
       memoryShardStore: deps.memoryShardStore || null,
       toolRegistry: childRegistry,
@@ -314,7 +317,29 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
 
   const dequeueNextUserPrompt = () => {
     if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
-    return agent.pendingPrompts.shift() || null;
+    const entry = agent.pendingPrompts.shift();
+    if (!entry) return null;
+    if (typeof entry === 'string') {
+      return {
+        prompt: entry,
+        projectSessionIds: Array.isArray(deps.projectSessionIds)
+          ? deps.projectSessionIds.slice()
+          : [],
+        projectInstruction: typeof deps.projectInstruction === 'string'
+          ? deps.projectInstruction
+          : '',
+      };
+    }
+    if (!entry || typeof entry !== 'object' || typeof entry.prompt !== 'string') return null;
+    return {
+      prompt: entry.prompt,
+      projectSessionIds: Array.isArray(entry.projectSessionIds)
+        ? entry.projectSessionIds.slice()
+        : [],
+      projectInstruction: typeof entry.projectInstruction === 'string'
+        ? entry.projectInstruction
+        : '',
+    };
   };
 
   try {
@@ -329,8 +354,8 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
     emit({ type: 'sub_agent_status', status: STATUS.RUNNING });
 
     while (!isTerminalAgentStatus(agent.status)) {
-      const prompt = dequeueNextUserPrompt();
-      if (!prompt) {
+      const queuedPrompt = dequeueNextUserPrompt();
+      if (!queuedPrompt) {
         // No queued work — go idle and wait for PromptAgent / CloseAgent /
         // watchdog.
         agent.status = STATUS.IDLE;
@@ -375,15 +400,14 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
       let turnUsageTokens = 0;
       try {
         const stream = subEngine.query({
-          prompt,
+          prompt: queuedPrompt.prompt,
           messages: agent.engineMessages,
           signal: agent.abortController?.signal,
           scenario: 'chat',
           vpPersona,
           sessionId: agent.parentSessionId || deps.parentSessionId || null,
-          projectSessionIds: Array.isArray(deps.projectSessionIds)
-            ? deps.projectSessionIds
-            : null,
+          projectSessionIds: queuedPrompt.projectSessionIds,
+          projectInstruction: queuedPrompt.projectInstruction,
         });
         for await (const evt of stream) {
           // Liveness — update first so even listener throws don't lose
@@ -446,7 +470,7 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
 
       // Persist the turn into the local message buffer so subsequent
       // PromptAgent continuations see context.
-      agent.engineMessages.push({ role: 'user', content: prompt });
+      agent.engineMessages.push({ role: 'user', content: queuedPrompt.prompt });
       if (assistantText) {
         agent.engineMessages.push({ role: 'assistant', content: assistantText });
       }

package/yeaft/tools/send-message.js

@@ -7,6 +7,7 @@
 
 import { defineTool } from './types.js';
 import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
+import { enqueueSubAgentPrompt } from '../sub-agent/prompt-queue.js';
 import { isTerminalAgentStatus, isPromptableAgentStatus, STATUS, describeAgentStatus } from '../sub-agent/status.js';
 
 export default defineTool({
@@ -111,8 +112,10 @@ SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用
 
     // Queue as a pending prompt the driver will pull. This wakes the
     // driver out of its idle wait and starts a new turn.
-    if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
-    agent.pendingPrompts.push(message);
+    enqueueSubAgentPrompt(agent, message, {
+      projectSessionIds: ctx?.parentEngineDeps?.projectSessionIds,
+      projectInstruction: ctx?.parentEngineDeps?.projectInstruction,
+    });
     agent.messages.push({
       role: 'user',
       content: message,

package/yeaft/web-bridge.js

@@ -72,6 +72,7 @@ import {
   moveSessionToProject,
   removeSessionFromProjects,
   renameProject,
+  updateProjectInstruction,
 } from './projects/store.js';
 import { readSummary as readScopeSummary } from './memory/store.js';
 import { estimateTokens } from './dream/segment.js';
@@ -84,6 +85,7 @@ import { classifyThread as defaultClassifyThread, fallbackTitle } from './vp/thr
 import { listMcpServers, upsertMcpServer, removeMcpServer } from './config-api.js';
 import { buildMcpFlattenedTools } from './tools/mcp-tools.js';
 import { getAgentRegistry, agentBelongsToScope } from './tools/agent.js';
+import { enqueueSubAgentPrompt } from './sub-agent/prompt-queue.js';
 import { isPromptableAgentStatus } from './sub-agent/status.js';
 import { perfNowMs, recordAgentPerfTrace } from './perf-trace.js';
 import { recordAgentSessionCreated, recordAgentTurn } from '../metrics.js';
@@ -602,6 +604,9 @@ function normalizeProjectContext(value, sessionId) {
     projectName: typeof value.projectName === 'string' && value.projectName.trim()
       ? value.projectName.trim()
       : null,
+    projectInstruction: typeof value.projectInstruction === 'string'
+      ? value.projectInstruction.trim()
+      : '',
     sessionIds: Array.from(new Set(value.sessionIds
       .filter(id => typeof id === 'string' && id.trim())
       .map(id => id.trim())
@@ -615,6 +620,7 @@ function legacyProjectContext(yeaftDir, sessionId) {
   return normalizeProjectContext({
     projectId: project.id,
     projectName: project.name,
+    projectInstruction: project.instruction || '',
     sessionIds: project.sessionIds,
   }, sessionId);
 }
@@ -3198,6 +3204,20 @@ export function handleYeaftListSessions(msg) {
   }
 }
 
+export function handleYeaftProjectContextSync(msg) {
+  for (const row of Array.isArray(msg?.contexts) ? msg.contexts : []) {
+    const sessionId = typeof row?.sessionId === 'string' ? row.sessionId.trim() : '';
+    if (!sessionId) continue;
+    const projectContext = normalizeProjectContext(row.projectContext, sessionId);
+    projectContextBySession.set(sessionId, projectContext || {
+      projectId: null,
+      projectName: null,
+      projectInstruction: '',
+      sessionIds: [],
+    });
+  }
+}
+
 export function handleYeaftProjectMutation(msg) {
   const requestId = msg && msg.requestId;
   const op = msg && msg.op;
@@ -3206,7 +3226,9 @@ export function handleYeaftProjectMutation(msg) {
     let result = null;
     if (op === 'create') result = createProject(yeaftDir, msg.name);
     else if (op === 'rename') result = renameProject(yeaftDir, msg.projectId, msg.name);
-    else if (op === 'delete') result = deleteProject(yeaftDir, msg.projectId);
+    else if (op === 'update_instruction') {
+      result = updateProjectInstruction(yeaftDir, msg.projectId, msg.instruction);
+    } else if (op === 'delete') result = deleteProject(yeaftDir, msg.projectId);
     else if (op === 'move_session') {
       if (!snapshotSessions(yeaftDir).some(row => row.id === msg.sessionId)) {
         throw new ProjectStoreError('session_not_found', 'Session not found');
@@ -4568,6 +4590,7 @@ async function runYeaftSessionSend(msg) {
     projectContextBySession.set(sessionId, inboundProjectContext || {
       projectId: null,
       projectName: null,
+      projectInstruction: '',
       sessionIds: [],
     });
   } else {
@@ -5250,6 +5273,7 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
           || legacyProjectContext(ctx.CONFIG?.yeaftDir, sessionId);
         const projectSessionIds = projectContext?.sessionIds || [];
         queryOpts.projectSessionIds = projectSessionIds;
+        queryOpts.projectInstruction = projectContext?.projectInstruction || '';
         const projectSummaries = await sharedProjectContext(ctx.CONFIG?.yeaftDir, sessionId, {
           sessionIds: projectSessionIds,
           language: session?.config?.language,
@@ -6497,8 +6521,12 @@ export function handleYeaftSubAgentPrompt(msg) {
     return;
   }
 
-  if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
-  agent.pendingPrompts.push(message);
+  const projectContext = projectContextBySession.get(sessionId)
+    || legacyProjectContext(ctx.CONFIG?.yeaftDir, sessionId);
+  enqueueSubAgentPrompt(agent, message, {
+    projectSessionIds: projectContext?.sessionIds,
+    projectInstruction: projectContext?.projectInstruction,
+  });
   if (!Array.isArray(agent.messages)) agent.messages = [];
   agent.messages.push({ role: 'user', content: message, timestamp: Date.now() });
   if (agent.status === 'idle' || agent.status === 'created') agent.status = 'running';
@@ -7385,6 +7413,12 @@ export const __testHooks = {
   sharedProjectContext,
   buildProjectSharedBlock,
   normalizeProjectContext,
+  handleProjectContextSyncForTest(msg) {
+    handleYeaftProjectContextSync(msg);
+  },
+  projectContextForSessionForTest(sessionId) {
+    return projectContextBySession.get(sessionId) || null;
+  },
   loadVisibleGroupHistoryPage,
   projectVisibleHistoryChunkMessages,
   persistInboundMessageOnceByMsgId,