fuli-context 0.5.0 → 0.7.2

package/src/cli/setup-command.js

@@ -7,6 +7,10 @@ import {
 } from './setup-agent-selection.js';
 import { parseSetupOptions } from '../setup/options.js';
 import { applyLocalSetup, planLocalSetup } from '../setup/setup.js';
+import {
+  DEFAULT_RUNTIME_SETTINGS,
+  runtimeSettingsWithOverrides
+} from '../system/runtime-settings.js';
 
 export async function runSetupCommand(args, dependencies = {}) {
   const options = parseSetupOptions(args);
@@ -23,7 +27,7 @@ export async function runSetupCommand(args, dependencies = {}) {
   write(formatSetupPreview(plan, options));
 
   if (!options.yes && !await confirm()) {
-    write('已取消，没有修改任何内容。');
+    write('Cancelled. No changes were made.');
     return { status: 'cancelled' };
   }
 
@@ -39,33 +43,50 @@ export function formatSetupPreview(plan, options) {
   const available = plan.agents.filter(({ available }) => available);
   const selected = available.filter(({ selected }) => selected !== false);
   const agentSummary = options.skipAgents || (available.length > 0 && selected.length === 0)
-    ? '跳过接入'
-    : selected.map(({ label }) => label).join('、') || '未检测到';
+    ? 'skipped'
+    : selected.map(({ label }) => label).join(', ') || 'none detected';
+  const runtimeSettings = plan.runtimeSettings ?? runtimeSettingsWithOverrides(
+    DEFAULT_RUNTIME_SETTINGS,
+    { consolePort: options.port }
+  );
   return [
-    '准备设置复利',
+    'Ready to set up Fuli',
     options.personalOnly
-      ? '存储：仅个人：本机 Graphiti / Neo4j'
-      : '存储：本机 Graphiti / Neo4j + 团队共享项目 Provider',
-    '容器运行时：自动检测；已安装但未运行时会自动启动',
-    `公共服务：${options.personalOnly ? '暂不连接' : '连接本机开发 Provider'}`,
-    `个人空间：${options.personalSpaceName}`,
-    `本地控制台：${options.noStart ? '暂不启动' : `http://127.0.0.1:${options.port}`}`,
-    `Agent：${agentSummary}`
+      ? 'Storage: personal only, using local Graphiti / Neo4j'
+      : 'Storage: local Graphiti / Neo4j plus a development shared-project Provider',
+    'Container runtime: detected automatically; an installed desktop runtime starts if needed',
+    `Shared services: ${options.personalOnly ? 'not connected' : 'local development Provider'}`,
+    `Personal space: ${options.personalSpaceName}`,
+    `Management UI: ${options.noStart
+      ? 'will not start'
+      : `http://127.0.0.1:${runtimeSettings.ports.console}`}`,
+    `Agents: ${agentSummary}`
   ].join('\n');
 }
 
 export function formatSetupResult(result, plan) {
-  const lines = [result.status === 'ready' ? '复利已准备好。' : '复利已启动，但有 Agent 未连接。'];
-  if (result.runtime.url) lines.push(`打开：${result.runtime.url}`);
-  lines.push('知识存储：Graphiti / Neo4j');
+  const lines = [result.status === 'ready'
+    ? 'Fuli is ready.'
+    : 'Fuli started, but one or more Agents are not connected.'];
+  if (result.runtime.url) lines.push(`Open: ${result.runtime.url}`);
+  if (result.runtime.lan === true) {
+    lines.push(
+      'LAN URLs:',
+      ...result.runtime.lanUrls.map((url) => `  ${url}`),
+      `Username: ${result.runtime.lanAccess.username}`,
+      `Temporary access code: ${result.runtime.lanAccess.accessCode}`,
+      'Use only on trusted Wi-Fi. Restarting LAN mode rotates the access code.'
+    );
+  }
+  lines.push('Knowledge storage: Graphiti / Neo4j');
   for (const agent of result.agents) {
     if (agent.status !== 'connected') {
-      lines.push(`${agent.label}：连接失败，请稍后重试 setup`);
+      lines.push(`${agent.label}: connection failed; retry setup later`);
       continue;
     }
     lines.push(agent.newTaskRequired
-      ? `${agent.label}：已连接；请新建或重新打开一个任务以加载新配置`
-      : `${agent.label}：已连接`);
+      ? `${agent.label}: connected; create or reopen a task to load the new configuration`
+      : `${agent.label}: connected`);
   }
   return lines.join('\n');
 }
@@ -73,7 +94,9 @@ export function formatSetupResult(result, plan) {
 async function confirmInTerminal() {
   const input = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = (await input.question('只会修改以上内容，继续？[Y/n] ')).trim().toLowerCase();
+    const answer = (await input.question('Only the items above will change. Continue? [Y/n] '))
+      .trim()
+      .toLowerCase();
     return answer === '' || answer === 'y' || answer === 'yes';
   } finally {
     input.close();

package/src/cli/shell-argument.js

@@ -0,0 +1,10 @@
+export function quoteShellArgument(value, platform = process.platform) {
+  const argument = String(value);
+  if (platform === 'win32') {
+    if (argument.includes('"')) {
+      throw new TypeError('Windows paths cannot contain a double quote');
+    }
+    return `"${argument}"`;
+  }
+  return `'${argument.replaceAll("'", "'\\''")}'`;
+}

package/src/cli/uninstall-command.js

@@ -14,7 +14,7 @@ export async function runUninstallCommand(args, dependencies = {}) {
   write(formatUninstallPreview(plan));
 
   if (!options.yes && !await confirm()) {
-    write('已取消，没有修改任何内容。');
+    write('Cancelled. No changes were made.');
     return { status: 'cancelled' };
   }
 
@@ -24,30 +24,32 @@ export async function runUninstallCommand(args, dependencies = {}) {
 }
 
 export function formatUninstallPreview(plan) {
-  const labels = plan.agents.map(({ label }) => label).join('、') || '无';
+  const labels = plan.agents.map(({ label }) => label).join(', ') || 'none';
   return [
-    '准备清理复利的本机接入',
-    '本地服务：停止',
-    `Agent 接入：${labels}`,
-    'Skills：仅删除与当前安装包完全一致的副本；有本地修改的会保留',
-    `数据：保留 ${plan.paths.dataDir}`,
-    'Neo4j 数据卷：保留'
+    'Ready to remove local Fuli integrations',
+    'Local services: stop',
+    `Agent integrations: ${labels}`,
+    'Skills: remove only copies identical to this package; preserve locally modified copies',
+    `Data: preserve ${plan.paths.dataDir}`,
+    'Neo4j volumes: preserve'
   ].join('\n');
 }
 
 export function formatUninstallResult(result) {
   const lines = [
-    result.status === 'ready' ? '复利本机接入已清理。' : '复利本机接入未完全清理。',
-    `数据已保留：${result.data.path}`,
-    `最后移除全局命令：npm uninstall --global ${FULI_PACKAGE_NAME}`
+    result.status === 'ready'
+      ? 'Local Fuli integrations were removed.'
+      : 'Some local Fuli integrations could not be removed.',
+    `Data preserved: ${result.data.path}`,
+    `Finally, remove the global command: npm uninstall --global ${FULI_PACKAGE_NAME}`
   ];
   if (result.runtime.status !== 'stopped') {
-    lines.push(`本地服务：${result.runtime.message ?? '未能安全确认已停止'}`);
+    lines.push(`Local services: ${result.runtime.message ?? 'could not safely confirm they stopped'}`);
   }
   for (const agent of result.agents) {
     const modified = agent.skills.some(({ status }) => status === 'preserved_modified');
-    if (modified) lines.push(`${agent.label}：保留了有本地修改的 Skill`);
-    if (agent.errors?.length) lines.push(`${agent.label}：${agent.errors.join('；')}`);
+    if (modified) lines.push(`${agent.label}: preserved a locally modified Skill`);
+    if (agent.errors?.length) lines.push(`${agent.label}: ${agent.errors.join('; ')}`);
   }
   return lines.join('\n');
 }
@@ -55,7 +57,7 @@ export function formatUninstallResult(result) {
 async function confirmInTerminal() {
   const input = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = (await input.question('继续清理本机接入？[y/N] ')).trim().toLowerCase();
+    const answer = (await input.question('Remove local integrations? [y/N] ')).trim().toLowerCase();
     return answer === 'y' || answer === 'yes';
   } finally {
     input.close();

package/src/cli/update-command.js

@@ -7,7 +7,7 @@ import {
   FULI_PACKAGE_NAME,
   FULI_VERSION
 } from '../package-metadata.js';
-import { quoteShellArgument } from '../runtime-options.js';
+import { quoteShellArgument } from './shell-argument.js';
 import { parseUpdateOptions } from '../setup/options.js';
 import { runLocalRuntimeCommand } from './local-runtime-command.js';
 
@@ -31,7 +31,7 @@ export async function runUpdateCommand(args = [], dependencies = {}) {
 
   write(formatUpdatePreview(options));
   if (!options.yes && !await confirm()) {
-    write('已取消，没有修改任何内容。');
+    write('Cancelled. No changes were made.');
     return { status: 'cancelled' };
   }
 
@@ -51,13 +51,13 @@ export async function runUpdateCommand(args = [], dependencies = {}) {
   const stopped = await stopRuntime('stop', stopArgs, { env, write });
   if (stopped.status === 'partial') {
     throw new Error([
-      '无法安全确认旧版界面进程已停止，更新尚未开始。',
-      '请先运行 fuli status 检查本地状态，再重试 fuli update。'
+      'Could not safely confirm that the previous UI process stopped. The update did not start.',
+      'Run fuli status to inspect the local state, then retry fuli update.'
     ].join('\n'));
   }
 
   const selectedPackage = `${FULI_PACKAGE_NAME}@${latestVersion}`;
-  write(`正在安装 ${selectedPackage}（npm latest）…`);
+  write(`Installing ${selectedPackage} (npm latest)...`);
   const installed = runInherited(npmCommand, [
     'install',
     '--global',
@@ -67,15 +67,16 @@ export async function runUpdateCommand(args = [], dependencies = {}) {
   ], { env });
   if (!processSucceeded(installed)) {
     throw new Error([
-      `全局包安装失败（${describeProcessFailure(installed)}）。知识数据未删除。`,
-      `请先运行 npm install --global ${LATEST_PACKAGE}，再运行 fuli setup --yes。`
+      `Global package installation failed (${describeProcessFailure(installed)}). ` +
+        'Knowledge data was not deleted.',
+      `Run npm install --global ${LATEST_PACKAGE}, then run fuli setup --yes.`
     ].join('\n'));
   }
 
   const globalRootResult = runCaptured(npmCommand, ['root', '--global'], { env });
   if (!processSucceeded(globalRootResult)) {
     throw postInstallError(
-      `无法定位 npm 全局安装目录（${describeProcessFailure(globalRootResult)}）`,
+      `Could not locate the global npm directory (${describeProcessFailure(globalRootResult)})`,
       args,
       platform
     );
@@ -83,33 +84,35 @@ export async function runUpdateCommand(args = [], dependencies = {}) {
   const globalRoot = String(globalRootResult.stdout ?? '').trim();
   const cliPath = resolveGlobalCliPath(globalRoot, platform);
   if (!cliPath || !fileExists(cliPath)) {
-    throw postInstallError('新版 CLI 文件不存在，请重新安装全局包', args, platform);
+    throw postInstallError('The new CLI file is missing; reinstall the global package', args, platform);
   }
 
   const versionResult = runCaptured(nodePath, [cliPath, '--version'], { env });
   if (!processSucceeded(versionResult)) {
     throw postInstallError(
-      `新版 CLI 无法启动（${describeProcessFailure(versionResult)}）`,
+      `The new CLI could not start (${describeProcessFailure(versionResult)})`,
       args,
       platform
     );
   }
   const version = String(versionResult.stdout ?? '').trim();
-  if (!version) throw postInstallError('新版 CLI 未返回版本号', args, platform);
+  if (!version) throw postInstallError('The new CLI returned no version', args, platform);
   if (compareSemanticVersions(version, latestVersion) !== 0) {
     throw postInstallError(
-      `新版 CLI 版本 ${version} 与更新前确认的 npm latest ${latestVersion} 不一致`,
+      `The new CLI version ${version} does not match the npm latest version ${latestVersion} ` +
+        'confirmed before the update',
       args,
       platform
     );
   }
 
-  write('正在使用新版 CLI 刷新本机服务、Agent 接入和 Skills…');
+  write('Refreshing local services, Agent integrations, and Skills with the new CLI...');
   const setupArgs = ['setup', '--yes', ...args.filter((arg) => arg !== '--yes')];
   const setupResult = runInherited(nodePath, [cliPath, ...setupArgs], { env });
   if (!processSucceeded(setupResult)) {
     throw postInstallError(
-      `新版已安装，但 setup 未完成（${describeProcessFailure(setupResult)}）`,
+      `The new version was installed, but setup did not complete ` +
+        `(${describeProcessFailure(setupResult)})`,
       args,
       platform
     );
@@ -126,27 +129,32 @@ export async function runUpdateCommand(args = [], dependencies = {}) {
 
 export function formatUpdatePreview(options) {
   return [
-    '准备更新复利',
-    `npm 包：${LATEST_PACKAGE}`,
+    'Ready to update Fuli',
+    `npm package: ${LATEST_PACKAGE}`,
     options.noStart
-      ? '本地界面：安全停止；更新后保持关闭'
-      : '本地服务：安全停止；更新后由新版重新启动',
-    options.dataDir ? `数据：保留 ${options.dataDir}` : '数据：保留当前默认数据目录',
-    `Agent 接入与 Skills：${options.skipAgents ? '按参数跳过刷新' : '由新版 setup 刷新'}`
+      ? 'Local UI: stop safely and keep stopped after the update'
+      : 'Local services: stop safely and restart with the new version',
+    options.dataDir
+      ? `Data: preserve ${options.dataDir}`
+      : 'Data: preserve the current default data directory',
+    `Agent integrations and Skills: ${options.skipAgents
+      ? 'skip refresh as requested'
+      : 'refresh through setup in the new version'}`
   ].join('\n');
 }
 
 export function formatUpdateResult(result) {
   if (result.status === 'ahead') {
     return [
-      `当前 CLI 版本 ${result.version} 高于 npm latest ${result.latestVersion}；`,
-      '为避免降级，未停止服务、未安装包，也未修改 Agent 接入。'
+      `The current CLI version ${result.version} is newer than npm latest ${result.latestVersion}. `,
+      'To avoid a downgrade, services were not stopped, no package was installed, and Agent ' +
+        'integrations were not changed.'
     ].join('');
   }
   if (result.status === 'current') {
-    return `复利已是最新版本 ${result.version}；本机接入已刷新。`;
+    return `Fuli is already at the latest version (${result.version}); local integrations refreshed.`;
   }
-  return `复利已从 ${result.previousVersion} 更新到 ${result.version}。`;
+  return `Fuli updated from ${result.previousVersion} to ${result.version}.`;
 }
 
 export function compareSemanticVersions(left, right) {
@@ -185,8 +193,8 @@ export function resolveGlobalCliPath(globalRoot, platform = process.platform) {
 
 function postInstallError(message, args, platform) {
   return new Error([
-    `${message}。知识数据未删除。`,
-    `请重新运行：${formatSetupRecoveryCommand(args, platform)}`
+    `${message}. Knowledge data was not deleted.`,
+    `Run again: ${formatSetupRecoveryCommand(args, platform)}`
   ].join('\n'));
 }
 
@@ -198,8 +206,8 @@ function queryLatestVersion(npmCommand, runCaptured, env) {
   );
   if (!processSucceeded(result)) {
     throw new Error([
-      `无法检查 ${LATEST_PACKAGE}（${describeProcessFailure(result)}）。`,
-      '本地服务尚未停止，也没有安装或修改任何包。'
+      `Could not check ${LATEST_PACKAGE} (${describeProcessFailure(result)}).`,
+      'Local services were not stopped, and no package was installed or changed.'
     ].join('\n'));
   }
   const raw = String(result.stdout ?? '').trim();
@@ -244,7 +252,7 @@ function formatCommandArgument(value, platform) {
   try {
     return quoteShellArgument(value, platform);
   } catch {
-    return '<复用原参数>';
+    return '<reuse-original-argument>';
   }
 }
 
@@ -279,7 +287,7 @@ function spawnCaptured(command, args, { env }) {
 async function confirmInTerminal() {
   const input = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = (await input.question('将修改全局 npm 安装，继续？[Y/n] '))
+    const answer = (await input.question('This will modify the global npm installation. Continue? [Y/n] '))
       .trim()
       .toLowerCase();
     return answer === '' || answer === 'y' || answer === 'yes';

package/src/external-knowledge/catalog.js

@@ -0,0 +1,61 @@
+import { createCustomConnector } from './connectors/custom.js';
+import { createFeishuConnector } from './connectors/feishu.js';
+import { createMcpConnector } from './connectors/mcp.js';
+import { createNotionConnector } from './connectors/notion.js';
+import { createRetrievalApiConnector } from './connectors/retrieval-api.js';
+
+export function createConnectorCatalog({
+  customConnectorDirectory,
+  fetchImpl = globalThis.fetch,
+  mcpOpenSession,
+  sleep
+}) {
+  const connectors = [
+    withMetadata(createMcpConnector({ openSession: mcpOpenSession }), {
+      status: 'supported',
+      trust: 'remote_protocol',
+      description: 'MCP resources and explicitly configured read tools.'
+    }),
+    withMetadata(createNotionConnector({ fetchImpl }), {
+      status: 'supported',
+      trust: 'official_read_api',
+      description: 'Notion pages and data sources through the current markdown API.'
+    }),
+    withMetadata(createFeishuConnector({ fetchImpl, sleep }), {
+      status: 'supported',
+      trust: 'official_read_api',
+      description: 'Feishu/Lark wiki discovery and read-only docx content.',
+      limitations: ['docx_content_only', 'wiki_search_requires_user_access_token']
+    }),
+    withMetadata(createRetrievalApiConnector({ fetchImpl }), {
+      status: 'supported',
+      trust: 'compatible_read_api',
+      description: 'Dify-compatible retrieval API for external RAG knowledge bases.',
+      limitations: ['live_retrieval_only', 'requires_stable_document_metadata_for_best_provenance']
+    }),
+    withMetadata(createCustomConnector({ directory: customConnectorDirectory }), {
+      status: 'advanced',
+      trust: 'trusted_local_code',
+      description: 'A local ESM connector module explicitly installed by the user.'
+    })
+  ];
+  const byType = new Map(connectors.map((connector) => [connector.type, connector]));
+  return {
+    get(type) {
+      return byType.get(type) ?? null;
+    },
+    list() {
+      return connectors.map(({ metadata }) => structuredClone(metadata));
+    }
+  };
+}
+
+function withMetadata(connector, metadata) {
+  const descriptor = Object.freeze({
+    type: connector.type,
+    name: connector.name,
+    capabilities: [...connector.capabilities],
+    ...metadata
+  });
+  return Object.assign(connector, { metadata: descriptor });
+}

package/src/external-knowledge/conflict-policy.js

@@ -0,0 +1,58 @@
+import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
+
+const MODES = new Set(['ask_human', 'agent_decide']);
+const EMPTY_POLICIES = Object.freeze({ version: 1, projects: {} });
+
+export class KnowledgeConflictPolicyStore {
+  constructor(filePath, { now = () => new Date() } = {}) {
+    if (typeof filePath !== 'string' || !filePath.trim()) {
+      throw new TypeError('Knowledge conflict policy path is required');
+    }
+    this.filePath = filePath;
+    this.now = now;
+  }
+
+  get(personalProjectId) {
+    const id = requiredString(personalProjectId, 'personalProjectId');
+    const projects = this.#read().projects;
+    const stored = projects[policyKey(id)] ??
+      (Object.hasOwn(projects, id) ? projects[id] : null);
+    return stored
+      ? structuredClone(stored)
+      : { personalProjectId: id, mode: 'ask_human', updatedAt: null };
+  }
+
+  set(personalProjectId, mode) {
+    const id = requiredString(personalProjectId, 'personalProjectId');
+    if (!MODES.has(mode)) {
+      throw new TypeError('Conflict policy mode must be ask_human or agent_decide');
+    }
+    const document = this.#read();
+    const policy = {
+      personalProjectId: id,
+      mode,
+      updatedAt: this.now().toISOString()
+    };
+    document.projects[policyKey(id)] = policy;
+    writeJsonFileAtomic(this.filePath, document);
+    return structuredClone(policy);
+  }
+
+  #read() {
+    const document = readJsonFile(this.filePath, EMPTY_POLICIES);
+    if (document?.version !== 1 || !document.projects ||
+        typeof document.projects !== 'object' || Array.isArray(document.projects)) {
+      throw new TypeError('Unsupported knowledge conflict policy format');
+    }
+    return structuredClone(document);
+  }
+}
+
+function policyKey(personalProjectId) {
+  return `project:${personalProjectId}`;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
+  return value.trim();
+}

package/src/external-knowledge/connected-search.js

@@ -0,0 +1,166 @@
+import { safeExternalSourceDiagnostic } from './safe-diagnostic.js';
+
+export class ConnectedKnowledgeSearch {
+  constructor({ app, externalKnowledge, policies }) {
+    if (!app || !externalKnowledge || !policies) {
+      throw new TypeError('Connected knowledge search requires app, externalKnowledge, and policies');
+    }
+    this.app = app;
+    this.externalKnowledge = externalKnowledge;
+    this.policies = policies;
+  }
+
+  async query(input) {
+    const personalSpaceId = requiredString(input?.personalSpaceId, 'personalSpaceId');
+    const personalProjectId = requiredString(input?.personalProjectId, 'personalProjectId');
+    const query = requiredString(input?.query, 'query');
+    const limit = positiveInteger(input?.limit ?? 12, 'limit', 100);
+    const projectIds = stringArray(input?.projectIds, 'projectIds', 32);
+    const contextPersonalProjectIds = stringArray(
+      input?.contextPersonalProjectIds,
+      'contextPersonalProjectIds',
+      15
+    );
+    const [graph, bindings] = await Promise.all([
+      this.app.searchKnowledge({
+        personalSpaceId,
+        personalProjectId,
+        projectIds,
+        contextPersonalProjectIds,
+        personalProjectScope: input.personalProjectScope ?? 'bounded',
+        query,
+        limit,
+        includeHistorical: input.includeHistorical === true,
+        includePending: input.includePending !== false,
+        agentInvocation: true,
+        agentToolName: 'search_connected_knowledge'
+      }),
+      this.externalKnowledge.listBindings()
+    ]);
+    const selected = bindings.flatMap((binding) =>
+      binding.status === 'ready'
+        ? bindingTargets(binding)
+            .filter((target) =>
+              target.status !== 'error' &&
+              target.mode !== 'mirror' &&
+              target.personalSpaceId === personalSpaceId &&
+              target.personalProjectId === personalProjectId
+            )
+            .map((target) => ({ binding, target }))
+        : []
+    );
+    const retrieved = await Promise.allSettled(selected.map(({ binding, target }) =>
+      this.externalKnowledge.retrieveBinding(binding.id, {
+        query,
+        limit,
+        personalSpaceId: target.personalSpaceId,
+        personalProjectId: target.personalProjectId
+      })
+    ));
+    const external = [];
+    const sourceErrors = [];
+    for (const [index, outcome] of retrieved.entries()) {
+      const { binding, target } = selected[index];
+      const identity = {
+        id: binding.id,
+        name: binding.name,
+        connectorType: binding.connectorType,
+        targetId: target.id,
+        mode: target.mode
+      };
+      if (outcome.status === 'fulfilled') {
+        external.push({
+          binding: identity,
+          items: outcome.value.items ?? [],
+          skippedCredentials: outcome.value.skippedCredentials ?? 0
+        });
+      } else {
+        sourceErrors.push({
+          binding: identity,
+          error: safeExternalSourceDiagnostic(outcome.reason)
+        });
+      }
+    }
+    const conflictPolicy = this.policies.get(personalProjectId);
+    return {
+      query,
+      graph,
+      external,
+      sourceErrors,
+      sourceScopes: {
+        personalProjectId,
+        publicProjectIds: projectIds,
+        publicSpaceStatus: projectIds.length ? 'beta' : 'not_requested'
+      },
+      conflictPolicy,
+      conflictAssessmentRequired: requiresConflictAssessment({
+        graph,
+        external,
+        publicProjectIds: projectIds
+      }),
+      conflictGuidance: guidanceFor(conflictPolicy.mode)
+    };
+  }
+
+  getConflictPolicy({ personalProjectId }) {
+    return this.policies.get(personalProjectId);
+  }
+
+  async updateConflictPolicy({ personalSpaceId, personalProjectId, mode }) {
+    const projects = await this.app.listPersonalProjects({ personalSpaceId });
+    if (!projects.some(({ project_id: id, id: fallback }) =>
+      (id ?? fallback) === personalProjectId
+    )) {
+      throw new TypeError('Conflict policy target must be an existing personal project');
+    }
+    return this.policies.set(personalProjectId, mode);
+  }
+}
+
+function bindingTargets(binding) {
+  if (Array.isArray(binding.targets)) return binding.targets;
+  return binding.target ? [{
+    id: binding.id,
+    ...binding.target,
+    mode: binding.mode,
+    status: binding.status
+  }] : [];
+}
+
+function guidanceFor(mode) {
+  return mode === 'agent_decide'
+    ? 'When sources materially conflict, the Agent may decide for this response only. Explain the basis and source provenance; never rewrite, confirm, or invalidate underlying knowledge automatically.'
+    : 'When sources materially conflict, surface the conflict in the Agent conversation and ask the user before selecting durable truth. Do not rewrite any source.';
+}
+
+function hasGraphEvidence(graph) {
+  return (graph?.facts?.length ?? 0) > 0 || (graph?.entities?.length ?? 0) > 0;
+}
+
+function requiresConflictAssessment({ graph, external, publicProjectIds }) {
+  const graphHasEvidence = hasGraphEvidence(graph);
+  const liveSourceCount = external.filter(({ items }) => items.length > 0).length;
+  return (graphHasEvidence ? 1 : 0) + liveSourceCount > 1 ||
+    (graphHasEvidence && publicProjectIds.length > 0);
+}
+
+function stringArray(value, label, maximum) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.length > maximum ||
+      value.some((item) => typeof item !== 'string' || !item.trim())) {
+    throw new TypeError(`${label} must be an array of at most ${maximum} nonempty strings`);
+  }
+  return [...new Set(value.map((item) => item.trim()))];
+}
+
+function positiveInteger(value, label, maximum) {
+  if (!Number.isInteger(value) || value <= 0 || value > maximum) {
+    throw new TypeError(`${label} must be a positive integer no greater than ${maximum}`);
+  }
+  return value;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
+  return value.trim();
+}