@yeaft/webchat-agent 1.0.513 → 1.0.515

package/yeaft/prompts.js

@@ -9,12 +9,10 @@
  *
  * Concept layering (DESIGN-PROMPT §3):
  *   ① Identity      — VP persona body (or Yeaft fallback)
- *   ② Rules         — session announcement, date, mode template, tools,
- *                     tool-guidance, skills, common rules
+ *   ② Rules         — Session/Project instructions, date, runtime, and skills
  *   ③ Memory        — single block produced upstream by the AMS render
  *                     outlet and threaded through here as `memoryInjection`
- *   ④ Active Scope  — structured per-turn scope summary
- *                     (session / vp / members / envelope IDs)
+ *   ④ Routing       — multi-VP identity and handoff metadata when applicable
  *
  * Long-term semantic context comes only from the AMS Memory outlet. The
  * conversation transcript stays in the messages timeline and is bounded by
@@ -142,7 +140,6 @@ const RAW_TEMPLATES = {
   commonRules: readTemplate('common-rules.md', { required: false }),
   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.
@@ -192,12 +189,6 @@ const PROMPTS = {
     identity: 'No VP soul is active for this turn. Participate in the current session with grounded, evidence-based answers and preserve the user\'s context.',
     date: (d) => `Date: ${d}`,
     dream: 'You are in dream mode. Reflect on past conversations and consolidate memories.',
-    // DESIGN-PROMPT §3 ④ — current session context block.
-    activeScopeHeader: '## Current session context',
-    activeScopeSessionIdLabel: 'Session ID',
-    activeScopeMembersLabel: 'Session members',
-    activeScopeTopicsLabel: 'Current focus',
-    activeScopeEnvelopeLabel: 'Handoff',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[Session Announcement]',
     projectInstructionHeader: '[Project Instruction]',
@@ -218,12 +209,6 @@ const PROMPTS = {
     identity: '你正在当前会话中参与协作。保持用户上下文，回答要基于证据；需要工具时使用工具，但不要把自己没有实际执行过的事说成已经执行。',
     date: (d) => `日期：${d}`,
     dream: '你处于梦境模式。回顾过去的对话，整理和巩固记忆。',
-    // DESIGN-PROMPT §3 ④ — 当前会话上下文。
-    activeScopeHeader: '## 当前会话上下文',
-    activeScopeSessionIdLabel: '会话 ID',
-    activeScopeMembersLabel: '会话成员',
-    activeScopeTopicsLabel: '当前讨论',
-    activeScopeEnvelopeLabel: '转交消息',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[会话公告]',
     projectInstructionHeader: '[Project 指令]',
@@ -275,28 +260,22 @@ export function normalizePromptLanguage(language) {
  *
  * Prompt structure (DESIGN-PROMPT §3):
  *   ① Identity      — Core identity (persona or Yeaft fallback)
- *   ② Rules         — Session announcement, date, mode, tools, guidance, skills
+ *   ② Rules         — Session/Project instructions, date, runtime, and skills
  *   ③ Memory        — Single block produced by the AMS render outlet
  *                     (callers pass it as `memoryInjection`).
- *   ④ Active Scope  — Structured per-turn scope summary
- *                     (session / vp / members / envelope IDs).
- *   (The previous standalone user_profile / core_memory blocks are
- *    gone — those signals now arrive through AMS Resident. Task
- *    context (`taskCtx`) was wired into Active Scope by task-334e
- *    but never actually populated by the engine; removed 2026-05-13.)
+ *   ④ Routing       — Multi-VP identity and handoff metadata when applicable
  *
- *   Active Scope params (DESIGN-PROMPT §3 ④):
- *   @param {object} [activeScope] — structured scope summary for this turn
- *   @param {string} [activeScope.sessionId]
- *   @param {string} [activeScope.sessionMember]
- *   @param {string[]} [activeScope.sessionMembers]  current session roster
- *   @param {string[]} [activeScope.sessionTopics]   bounded topic labels for this session
- *   @param {object} [activeScope.envelope]          inbound routing info (sender, intent)
+ * Generic Session IDs, inferred topics, active-task labels, and repeated tool
+ * guidance are intentionally omitted from the system prompt.
+ *
+ *   Multi-VP routing params:
+ *   @param {object} [activeScope] — routing scope for this turn
+ *   @param {string} [activeScope.vpId]              current VP identity
+ *   @param {string[]} [activeScope.sessionMembers]  current Session roster
  *
  * @param {{
  *   language?: string,
  *   mode?: string,
- *   toolNames?: string[],
  *   memoryInjection?: string,
  *   skillContent?: string,
  *   activeScope?: object,
@@ -313,7 +292,6 @@ export function normalizePromptLanguage(language) {
 export function buildSystemPrompt({
   language = 'en',
   mode,
-  toolNames = [],
   memoryInjection,
   skillContent,
   activeScope,
@@ -324,7 +302,6 @@ export function buildSystemPrompt({
   workCenterInstructions = '',
   projectDoc = '',
   runtimePlatform,
-  activeTasks = '',
   promptNotices = [],
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
@@ -405,20 +382,15 @@ export function buildSystemPrompt({
     parts.push(dreamTemplate || lang.dream);
   }
 
-  // ─── 4. Runtime Platform + Tools + Tool Guidance ──────
+  // ─── 4. Runtime Platform ─────────────────────────────
+  // Tool schemas already carry their operational guidance. Repeating selected
+  // tool instructions in the system prompt wastes tokens and can drift from
+  // the executable schema, so only platform facts are rendered here.
   const runtimePlatformBlock = renderRuntimePlatformPrompt(runtimePlatform || getRuntimePlatformInfo(), effectiveLang);
   if (runtimePlatformBlock) {
     parts.push(runtimePlatformBlock);
   }
 
-  if (toolNames.length > 0) {
-    const guidance = renderActiveToolGuidance(toolNames, effectiveLang);
-    const toolGuidanceTemplate = getTemplate('toolGuidance', effectiveLang);
-    if (guidance && toolGuidanceTemplate) {
-      parts.push(toolGuidanceTemplate.replace('{{guidance}}', guidance));
-    }
-  }
-
   // ─── 5. Skills Section ─────────────────────────────────
   if (skillContent) {
     parts.push(skillContent);
@@ -436,16 +408,10 @@ export function buildSystemPrompt({
     parts.push(memoryInjection.trim());
   }
 
-  // ─── 7. Active Scope (DESIGN-PROMPT §3 ④) ──────────────
-  // Structured per-turn scope summary. The group/vp/envelope identifiers
-  // are rendered as a leading line. (Per-task taskCtx sub-block was
-  // never wired and is removed 2026-05-13.)
-  const activeScopeBlock = renderActiveScope(activeScope, lang);
-  if (activeScopeBlock) parts.push(activeScopeBlock);
-
-  const activeTaskText = typeof activeTasks === 'string' ? activeTasks.trim() : '';
-  if (activeTaskText) parts.push(activeTaskText);
-
+  // ─── 7. Multi-VP routing ────────────────────────────────
+  // Generic Session IDs, inferred topics, and live task labels are runtime
+  // bookkeeping rather than model instructions. Keep only the routing block
+  // whose peer identities and RouteForward contract affect model behaviour.
   const multiVpRoutingBlock = renderMultiVpRouting(activeScope, lang);
   if (multiVpRoutingBlock) parts.push(multiVpRoutingBlock);
 
@@ -454,64 +420,6 @@ export function buildSystemPrompt({
 
 // ─── helpers ─────────────────────────────────────────────────────
 
-const TOOL_GUIDANCE_GROUPS = Object.freeze([
-  {
-    tools: ['DiscoverTools'],
-    en: 'If the visible tools do not clearly cover the request, use `DiscoverTools` with the user goal before concluding that a capability is unavailable. If the target is absent from a page, follow `next_cursor` until found or the hidden directory is exhausted. If `restart_required` is true, restart without a cursor because the registered directory changed.',
-    zh: '如果可见工具不能明确覆盖请求，应先按用户目标调用 `DiscoverTools`。若当前页没有目标，应按 `next_cursor` 继续翻页，直到找到或隐藏目录耗尽后，才能判断某项能力不可用。如果 `restart_required` 为 true，说明注册目录已变化，应丢弃游标重新开始。',
-  },
-  {
-    tools: ['FileRead', 'FileWrite', 'FileEdit', 'Glob', 'Grep', 'ListDir', 'ApplyPatch', 'NotebookEdit'],
-    en: 'Read existing files before editing. Use dedicated file/search tools instead of shell search or `sed -i`; make small, reviewable edits. Parallelize only proven-independent reads under the accuracy-first rule above.',
-    zh: '编辑前先读现有文件。文件搜索和修改优先使用专用工具，不用 shell 搜索或 `sed -i`；改动保持小而可审查。只有明确满足上述准确性优先判据的读取才可并行。',
-  },
-  {
-    tools: ['Bash'],
-    en: 'Use non-interactive, deterministic shell commands, set reasonable timeouts, quote paths with spaces, and do not run destructive operations without authorization.',
-    zh: 'Shell 命令保持非交互、确定性并设置合理 timeout；包含空格的路径要引用，未经授权不要执行破坏性操作。',
-  },
-  {
-    tools: ['TodoWrite'],
-    en: 'For non-trivial multi-step work, write a brief visible plan and call `TodoWrite` in the same assistant response as the first necessary work-tool call only when its arguments and safety do not depend on another result. Start with the smallest such call; do not speculative-batch the investigation or stop after planning unless user input genuinely blocks the first step.',
-    zh: '非平凡多步骤任务先写简短可见计划。只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 `TodoWrite` 一起发出；先执行满足条件的最小调用，不要推测性批量展开调查。只有用户信息确实阻塞第一步时才在规划后停下。',
-  },
-  {
-    tools: ['SpawnAgent', 'PromptAgent', 'WaitAgent', 'CloseAgent', 'ListAgents'],
-    en: 'Delegate only independent, bounded work. Keep ownership in the parent. After PromptAgent queues follow-up work, call WaitAgent in the same parent turn and collect the reply before ending. If a bounded wait times out, wait again with a larger bound unless the agent is stale/stalled. Relay the reply or continue the dependent work, then close the sub-agent when it is no longer needed.',
-    zh: '只委派边界清晰且独立的工作。父级保留任务所有权。PromptAgent 排队后续工作后，必须在同一个父级 turn 调用 WaitAgent 并拿到回复再结束；有界等待超时后，除非 Agent 已 stale/stalled，否则使用更大上限继续等待；随后转述结果或继续依赖该结果的工作，不再需要时关闭子 Agent。',
-  },
-  {
-    tools: ['ListTasks', 'ReadTaskLog', 'CancelTask'],
-    en: 'Treat background tasks as live execution state, not memory facts. Inspect status or logs before retrying or cancelling work.',
-    zh: '后台任务是实时执行状态，不是记忆事实。重试或取消前先检查状态或日志。',
-  },
-  {
-    tools: ['RouteForward'],
-    en: 'Use `RouteForward` for explicit VP-to-VP handoff; writing an @mention in ordinary text does not dispatch another VP.',
-    zh: '显式 VP 转交必须使用 `RouteForward`；普通文本中的 @mention 不会调度另一个 VP。',
-  },
-  {
-    tools: ['CreateWorkItem'],
-    en: 'Use `CreateWorkItem` only for goals that need durable cross-turn coordination, recovery, review, waiting, or retry.',
-    zh: '只有目标需要跨 turn 持久协调、恢复、评审、等待或重试时才使用 `CreateWorkItem`。',
-  },
-]);
-
-function renderActiveToolGuidance(toolNames, language) {
-  const active = new Set(Array.isArray(toolNames) ? toolNames : []);
-  const lines = [];
-  if (active.size > 0) {
-    lines.push(language === 'zh'
-      ? '- 准确性优先：先用能解决当前未知的最小定向调用。只有每个调用都已经确定有必要，且其参数和安全性都不依赖同批其他结果时，才在一个响应中发出多个工具调用；否则串行执行。不要推测性扇出、重复成功的读取/搜索，也不要默认抓取多个来源；先检查证据，再决定是否扩展。'
-      : '- Accuracy first: start with the smallest targeted call that can resolve the current uncertainty. Issue multiple tool calls in one response only when every call is already necessary and its arguments and safety do not depend on another call\'s result. Otherwise run them sequentially. Do not fan out speculatively, repeat a successful read/search, or fetch multiple sources by default; inspect evidence before expanding.');
-  }
-  for (const group of TOOL_GUIDANCE_GROUPS) {
-    if (!group.tools.some(name => active.has(name))) continue;
-    lines.push(`- ${language === 'zh' ? group.zh : group.en}`);
-  }
-  return lines.join('\n');
-}
-
 /**
  * Render the VP identity block when the engine is running on behalf of an
  * addressed VP. The `persona` body from role.md is the only soul source;
@@ -570,32 +478,6 @@ function selectVpPersonaBody(vpPersona, effectiveLang) {
 
 
 
-function renderActiveScope(activeScope, lang) {
-  if (!activeScope || typeof activeScope !== 'object') return '';
-
-  const isZh = lang === PROMPTS.zh;
-  const separator = isZh ? '：' : ': ';
-  const lines = [];
-  const session = typeof activeScope.sessionId === 'string' && activeScope.sessionId.trim()
-    ? activeScope.sessionId.trim()
-    : '';
-  if (session) lines.push(`${lang.activeScopeSessionIdLabel}${separator}${session}`);
-
-  const membersLine = renderSessionMembersLine(activeScope.sessionMembers || activeScope.members, isZh);
-  if (membersLine) lines.push(`${lang.activeScopeMembersLabel}${separator}${membersLine}`);
-
-  const topicsLine = renderSessionTopicsLine(activeScope.sessionTopics, isZh);
-  if (topicsLine) lines.push(`${lang.activeScopeTopicsLabel}${separator}${topicsLine}`);
-
-  const envLine = renderEnvelopeLine(activeScope.envelope, isZh);
-  if (envLine) lines.push(`${lang.activeScopeEnvelopeLabel}${separator}${envLine}`);
-
-  if (lines.length === 0) return '';
-
-  return `${lang.activeScopeHeader}\n${lines.join('\n')}`;
-}
-
-
 function firstNonEmptyString(...values) {
   for (const value of values) {
     if (typeof value === 'string' && value.trim()) return value.trim();
@@ -603,151 +485,6 @@ function firstNonEmptyString(...values) {
   return '';
 }
 
-function renderSessionMembersLine(members, useChineseSeparator = false) {
-  return normalizeSessionMemberIds(members).join(useChineseSeparator ? '、' : ', ');
-}
-
-function renderSessionTopicsLine(topics, isZh = false) {
-  const descriptions = [];
-  const seen = new Set();
-  for (const topic of normalizeSessionTopicIds(topics)) {
-    const description = describeSessionTopic(topic, isZh);
-    if (!description || seen.has(description)) continue;
-    seen.add(description);
-    descriptions.push(description);
-  }
-  return descriptions.join(isZh ? '；' : '; ');
-}
-
-function normalizeSessionTopicIds(topics) {
-  if (!Array.isArray(topics)) return [];
-  const clean = [];
-  const seen = new Set();
-  for (const topic of topics) {
-    if (typeof topic !== 'string') continue;
-    const id = topic.trim();
-    if (!id || seen.has(id)) continue;
-    seen.add(id);
-    clean.push(id);
-  }
-  return clean;
-}
-
-function describeSessionTopic(topic, isZh = false) {
-  const normalized = topic.toLowerCase().replace(/[_\s]+/g, '-');
-
-  if (normalized.includes('dream') && normalized.includes('segments')) {
-    return isZh
-      ? '梦境记忆片段的抽取与整理'
-      : 'Dream memory segment extraction and organization';
-  }
-  if (normalized.includes('dream') && normalized.includes('session') && normalized.includes('extraction')) {
-    return isZh
-      ? '梦境会话记忆的抽取质量'
-      : 'Dream session-memory extraction quality';
-  }
-  if (normalized.includes('system-prompt') && normalized.includes('localization')) {
-    return isZh
-      ? '系统提示词的中英文一致性'
-      : 'system prompt language localization';
-  }
-  if (normalized.includes('default-character') && normalized.includes('prompt-soul')) {
-    return isZh
-      ? '默认角色灵魂提示词的表达方式'
-      : 'default persona soul prompt wording';
-  }
-  if (normalized.includes('prompt') && normalized.includes('soul')) {
-    return isZh
-      ? '角色灵魂提示词的表达方式'
-      : 'persona soul prompt wording';
-  }
-  if (normalized.includes('openai-responses')) {
-    return isZh
-      ? 'Yeaft 的 OpenAI Responses 适配与模型配置'
-      : 'Yeaft OpenAI Responses adapter and model configuration';
-  }
-  if (normalized.includes('model-config-isolation')) {
-    return isZh
-      ? 'Yeaft 的模型配置隔离'
-      : 'Yeaft model configuration isolation';
-  }
-  if (normalized.includes('route-forward') || normalized.includes('handoff')) {
-    return isZh
-      ? 'Yeaft 的会话路由交接与可见性'
-      : 'Yeaft session routing handoff and visibility';
-  }
-  if (normalized.includes('copilot-cli') || normalized.includes('chat-session')) {
-    return isZh
-      ? 'Copilot CLI 的聊天会话行为'
-      : 'Copilot CLI chat session behavior';
-  }
-  if (normalized.includes('claude-opus')) {
-    return isZh
-      ? 'Yeaft 的 Claude Opus 模型接入'
-      : 'Yeaft Claude Opus model integration';
-  }
-  if (normalized.includes('pr-workflow')) {
-    return isZh
-      ? '项目的 PR review、merge 和 tag 发布流程'
-      : 'project PR review, merge, and tag release workflow';
-  }
-  if (/\bpr[-/]?\d+\b/.test(normalized) || normalized.includes('release') || /v\d+\.\d+\.\d+/.test(normalized)) {
-    return isZh
-      ? '最近的 PR 修复、review、merge 和 tag 发布流程'
-      : 'recent PR fixes, review, merge, and tag release work';
-  }
-  if (normalized.includes('active-scope')) {
-    return isZh
-      ? '当前会话上下文的提示词呈现'
-      : 'current session context prompt rendering';
-  }
-  if (normalized.includes('prompt') || normalized.includes('system')) {
-    return isZh
-      ? '近期的系统提示词调整'
-      : humanizeTopicSlug(topic, false) || 'recent system prompt work';
-  }
-  if (normalized.includes('dream')) {
-    return isZh
-      ? '近期的 Dream 记忆维护工作'
-      : humanizeTopicSlug(topic, false) || 'recent Dream memory work';
-  }
-  if (normalized.includes('session')) {
-    return isZh
-      ? '近期的会话上下文调整'
-      : humanizeTopicSlug(topic, false) || 'recent session context work';
-  }
-
-  if (isZh) return '近期的项目协作事项';
-  return humanizeTopicSlug(topic, false) || 'recent session collaboration topics';
-}
-
-function humanizeTopicSlug(topic, isZh = false) {
-  if (isZh) return '';
-  const words = topic
-    .replace(/[\/_-]+/g, ' ')
-    .replace(/\bv\d+(?:\.\d+)+\b/gi, '')
-    .replace(/\bpr\s*\d+\b/gi, '')
-    .trim()
-    .split(/\s+/)
-    .filter(Boolean);
-  if (words.length === 0) return '';
-
-  const normalizedWords = words.map(word => {
-    const lower = word.toLowerCase();
-    if (lower === 'yeaft') return 'Yeaft';
-    if (lower === 'project') return 'project';
-    if (lower === 'config') return 'configuration';
-    if (lower === 'isolation') return 'isolation';
-    if (lower === 'rendering') return 'rendering';
-    if (lower === 'workflow') return 'workflow';
-    if (lower === 'session') return 'session';
-    if (lower === 'context') return 'context';
-    return word;
-  });
-
-  return normalizedWords.join(' ');
-}
-
 function normalizeSessionMemberIds(members) {
   if (!Array.isArray(members)) return [];
   const clean = [];
@@ -764,7 +501,7 @@ function normalizeSessionMemberIds(members) {
 
 function renderMultiVpRouting(activeScope, lang) {
   if (!activeScope || typeof activeScope !== 'object') return '';
-  const ownId = firstNonEmptyString(activeScope.sessionMember, activeScope.vpId);
+  const ownId = firstNonEmptyString(activeScope.vpId);
   const members = normalizeSessionMemberIds(activeScope.sessionMembers || activeScope.members);
   const peers = ownId ? members.filter((member) => member !== ownId) : members;
   if (peers.length === 0) return '';
@@ -793,33 +530,6 @@ function renderMultiVpRouting(activeScope, lang) {
   ].join('\n');
 }
 
-/**
- * Render a one-line envelope summary. Pulls the small set of routing
- * fields we surface to the LLM (sender, intent, originating user) and
- * leaves the rest in AMS. Returns '' when the envelope carries no
- * useful signal.
- *
- * @param {object|null|undefined} envelope
- * @returns {string}
- */
-function renderEnvelopeLine(envelope, isZh = false) {
-  if (!envelope || typeof envelope !== 'object') return '';
-  const segments = [];
-  const fromVp = typeof envelope.fromVpId === 'string' && envelope.fromVpId.trim()
-    ? envelope.fromVpId.trim()
-    : (typeof envelope.senderVpId === 'string' ? envelope.senderVpId.trim() : '');
-  if (fromVp) segments.push(`${isZh ? '来自' : 'from'}=${fromVp}`);
-  const fromUser = typeof envelope.fromUserId === 'string' && envelope.fromUserId.trim()
-    ? envelope.fromUserId.trim()
-    : '';
-  if (fromUser) segments.push(`${isZh ? '用户' : 'user'}=${fromUser}`);
-  const intent = typeof envelope.intent === 'string' && envelope.intent.trim()
-    ? envelope.intent.trim()
-    : '';
-  if (intent) segments.push(`${isZh ? '意图' : 'intent'}=${intent}`);
-  return segments.join(' ');
-}
-
 // ─── Phase 1: Worker / Router prompt splits ──────────────────────
 //
 // DESIGN.md (multi-VP redesign) describes two distinct prompt shapes:
@@ -830,7 +540,7 @@ function renderEnvelopeLine(envelope, isZh = false) {
 //     carries Layer-A summaries + UserProfile + CoreMemory, AMS OnDemand
 //     carries the per-turn FTS hits. The worker shape that survives is:
 //       harness/worker-shape   — optional descriptive metadata
-//       buildSystemPrompt(...) — ① Identity ② Rules ③ Memory ④ Active Scope
+//       buildSystemPrompt(...) — ① Identity ② Rules ③ Memory ④ Routing
 //       optional taskScope/turnScope — caller-provided pass-through strings
 //     `renderLayerASummaries` is no longer called inside the worker prompt
 //     because AMS already renders the same summaries — calling both was
@@ -891,15 +601,12 @@ export function renderLayerASummaries(summaries, language = 'en') {
  *
  * Output sections (DESIGN-PROMPT §3 layered concepts):
  *   harness/worker-shape (optional)   — descriptive metadata
- *   buildSystemPrompt(...)             — ① Identity ② Rules ③ Memory ④ Active Scope
+ *   buildSystemPrompt(...)             — ① Identity ② Rules ③ Memory ④ Routing
  *
- * Earlier task-322 / task-334e variants accepted `taskScope` and
- * `turnScope` pass-through strings so callers could append their own
- * scope blocks. DESIGN-PROMPT v1 retired that surface — Active Scope is
- * now structured (`activeScope: { sessionId, vpId, envelope }`) and
- * rendered by `buildSystemPrompt` itself. Both pass-through params
- * had zero remaining callers when v1 landed; removing them prevents the
- * "two ways to describe scope" drift §1 set out to eliminate.
+ * Earlier variants accepted `taskScope` and `turnScope` pass-through
+ * strings so callers could append their own scope blocks. That surface is
+ * retired. `activeScope` now carries only the VP identity and Session roster
+ * needed to render the deterministic multi-VP routing contract.
  *
  * @param {{
  *   language?: 'en'|'zh',
@@ -924,7 +631,7 @@ export function buildWorkerPrompt(params = {}) {
     if (shape) parts.push(shape);
   }
 
-  // Identity + Rules + Memory + Active Scope (DESIGN-PROMPT §3).
+  // Identity + Rules + Memory + Routing (DESIGN-PROMPT §3).
   const baseBlock = buildSystemPrompt({ ...rest, language: effectiveLang });
   if (baseBlock) parts.push(baseBlock);
 

package/yeaft/sessions/index.js

@@ -42,6 +42,7 @@ export {
   makeSessionId,
   ensureDefaultSessionIfEmpty,
   createSessionFromSpec,
+  copySession,
   renameSession,
   archiveSession,
   deleteSession,

package/yeaft/sessions/session-crud.js

@@ -63,6 +63,7 @@ import {
 } from '../conversation/history-index-state.js';
 import { retireConversationHistoryIndex } from '../conversation/history-index.js';
 import { ensureSessionConfigFile, saveSessionConfig, loadSessionConfig } from './session-config.js';
+import { ConversationStore } from '../conversation/persist.js';
 import { repairSessionStore } from './recovery.js';
 import {
   addOrUpdateManifestSession,
@@ -529,8 +530,13 @@ export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   if (!name) throw new SessionCrudError('invalid_name', null, 'group name required');
 
   const callerRoster = Array.isArray(input.roster) ? input.roster.slice() : [];
-  const fallbackVpId = callerRoster.length > 0 ? null : preferDefaultVp(scanSortedVpIds(libDir));
-  const roster = callerRoster.length > 0 ? callerRoster : (fallbackVpId ? [fallbackVpId] : []);
+  const preserveEmptyRoster = options.preserveEmptyRoster === true && Array.isArray(input.roster);
+  const fallbackVpId = callerRoster.length > 0 || preserveEmptyRoster
+    ? null
+    : preferDefaultVp(scanSortedVpIds(libDir));
+  const roster = callerRoster.length > 0 || preserveEmptyRoster
+    ? callerRoster
+    : (fallbackVpId ? [fallbackVpId] : []);
   // Validate every member up-front so we fail before touching fs.
   for (const vpId of roster) {
     if (isReservedVpId(vpId)) {
@@ -593,6 +599,62 @@ export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   return meta;
 }
 
+/**
+ * Create an independent Session from an existing Session's durable state.
+ * Project membership and server-owned asset storage intentionally remain with
+ * their existing owners; message payloads and their references are preserved.
+ */
+export function copySession(yeaftDir, sourceSessionId, options = {}) {
+  const sourceYeaftDir = resolveSessionYeaftDir(yeaftDir, sourceSessionId);
+  const source = requireSession(sourceYeaftDir, sourceSessionId);
+  let sourceMeta;
+  try {
+    sourceMeta = source.getMeta();
+  } finally {
+    source.close();
+  }
+
+  const requestedName = String(options.name || '').trim();
+  const name = requestedName || `${sourceMeta.name} copy`;
+  const sourceConfig = loadSessionConfig(sourceYeaftDir, sourceSessionId);
+  const copied = createSessionFromSpec(sourceYeaftDir, {
+    name,
+    roster: Array.isArray(sourceMeta.roster) ? sourceMeta.roster : [],
+    defaultVpId: sourceMeta.defaultVpId || null,
+    workDir: sourceMeta.workDir || '',
+  }, { ...options, preserveEmptyRoster: true });
+
+  try {
+    // Unlike ordinary Session creation, cloning is transactional: silently
+    // dropping a source override would make the copy behave differently.
+    saveSessionConfig(sourceYeaftDir, copied.id, sourceConfig);
+    const target = requireSession(sourceYeaftDir, copied.id);
+    try {
+      const targetMeta = target.getMeta();
+      target.saveMeta({
+        ...targetMeta,
+        announcement: sourceMeta.announcement || '',
+        metadataUpdatedAt: new Date().toISOString(),
+      });
+    } finally {
+      target.close();
+    }
+
+    const transcript = new ConversationStore(sourceYeaftDir);
+    const { copiedCount } = transcript.copySession(sourceSessionId, copied.id);
+    return { ...requireSessionMeta(sourceYeaftDir, copied.id), copiedMessageCount: copiedCount };
+  } catch (error) {
+    // A partial clone must never appear as a successful copy.
+    deleteSession(sourceYeaftDir, copied.id, options);
+    throw error;
+  }
+}
+
+function requireSessionMeta(yeaftDir, sessionId) {
+  const handle = requireSession(yeaftDir, sessionId);
+  try { return handle.getMeta(); } finally { handle.close(); }
+}
+
 /**
  * (A.2) Rename — updates meta.name; preserves everything else.
  */