fuli-context 0.2.0

package/src/local-runtime/lifecycle.js

@@ -0,0 +1,254 @@
+import { spawn } from 'node:child_process';
+import { existsSync, unlinkSync } from 'node:fs';
+
+import {
+  checkLocalConsoleHealth,
+  ensureGraphRuntime,
+  MANAGED_PERSONAL_PROVIDER_URL,
+  MANAGED_WORKSPACE_PROVIDER_URL,
+  stopGraphProviders
+} from '../setup/graph-runtime.js';
+import { readJsonFile } from '../storage/json-file.js';
+
+export async function startLocalRuntime(input, dependencies = {}) {
+  const deps = lifecycleDependencies(dependencies);
+  const config = deps.readConfig(input.paths.graphRuntimeConfigPath);
+  const managesDevelopmentWorkspace = hasManagedDevelopmentWorkspace(config);
+  const buildProviders = input.rebuild === true || !config ||
+    !deps.fileExists(input.paths.graphEnvPath);
+  const runtime = await deps.ensureRuntime({
+    paths: input.paths,
+    personalSpaceName: input.personalSpaceName,
+    port: input.port,
+    personalOnly: !managesDevelopmentWorkspace,
+    buildProviders,
+    noStart: false,
+    env: input.env,
+    onProgress: input.onProgress
+  });
+
+  if (input.open === true) await deps.openExternal(runtime.url);
+  return {
+    ...runtime,
+    managesDevelopmentWorkspace
+  };
+}
+
+export async function stopLocalRuntime(input, dependencies = {}) {
+  const deps = lifecycleDependencies(dependencies);
+  const config = deps.readConfig(input.paths.graphRuntimeConfigPath);
+  const state = deps.readState(input.paths.graphRuntimeStatePath);
+  const consoleResult = await stopRecordedConsole(state, input.paths, deps);
+  const managesDevelopmentWorkspace = state?.managedProviders?.includes(
+    'development-workspace'
+  ) || hasManagedDevelopmentWorkspace(config);
+
+  let providers = 'not_initialized';
+  if (deps.fileExists(input.paths.graphEnvPath)) {
+    deps.stopProviders(input.paths, input.paths.graphEnvPath, {
+      personalOnly: !managesDevelopmentWorkspace
+    });
+    providers = 'stopped';
+  }
+
+  const partial = consoleResult === 'unverified' || consoleResult === 'still_running';
+  return {
+    status: partial ? 'partial' : 'stopped',
+    console: consoleResult,
+    providers,
+    managesDevelopmentWorkspace
+  };
+}
+
+export async function restartLocalRuntime(input, dependencies = {}) {
+  const stopped = await stopLocalRuntime(input, dependencies);
+  if (stopped.status === 'partial') {
+    throw new Error('无法安全确认原本地界面的进程身份，已拒绝重启。');
+  }
+  const started = await startLocalRuntime(input, dependencies);
+  return { stopped, ...started, status: 'restarted' };
+}
+
+export async function inspectLocalRuntime(input, dependencies = {}) {
+  const deps = lifecycleDependencies(dependencies);
+  const config = deps.readConfig(input.paths.graphRuntimeConfigPath);
+  const state = deps.readState(input.paths.graphRuntimeStatePath);
+  const stateLooksOwned = isRuntimeState(state) && isLoopbackConsoleUrl(state.url);
+  const processAlive = stateLooksOwned && deps.isProcessAlive(state.pid);
+  const consoleReady = processAlive && await deps.consoleHealth(
+    state.url,
+    state.pid,
+    state.version
+  );
+  const personalUrl = config?.personal?.providerUrl ?? MANAGED_PERSONAL_PROVIDER_URL;
+  const personal = config
+    ? await deps.providerHealth(personalUrl)
+    : { url: personalUrl, status: 'not_configured' };
+  const workspaces = await Promise.all((config?.workspaces ?? []).map(async (workspace) => ({
+    ...(await deps.providerHealth(workspace.providerUrl)),
+    managedDevelopment: isManagedDevelopmentUrl(workspace.providerUrl)
+  })));
+
+  let status = 'stopped';
+  if (!config && !state) status = 'not_configured';
+  else if (consoleReady && personal.status === 'ready') status = 'running';
+  else if (processAlive || personal.status === 'ready') status = 'degraded';
+
+  return {
+    status,
+    console: {
+      status: consoleReady ? 'ready' : processAlive ? 'unverified' : 'stopped',
+      url: stateLooksOwned ? state.url : `http://127.0.0.1:${input.port}`,
+      pid: processAlive ? state.pid : null
+    },
+    personal,
+    public: {
+      configured: workspaces.length > 0,
+      status: publicProviderStatus(workspaces),
+      providers: workspaces
+    }
+  };
+}
+
+export async function openLocalConsole(input, dependencies = {}) {
+  const deps = lifecycleDependencies(dependencies);
+  const state = deps.readState(input.paths.graphRuntimeStatePath);
+  if (!isRuntimeState(state) || !isLoopbackConsoleUrl(state.url) ||
+      !deps.isProcessAlive(state.pid) ||
+      !await deps.consoleHealth(state.url, state.pid, state.version)) {
+    throw new Error('本地界面尚未运行，请先执行 fl start。');
+  }
+  await deps.openExternal(state.url);
+  return { status: 'opened', url: state.url };
+}
+
+async function stopRecordedConsole(state, paths, deps) {
+  if (!isRuntimeState(state)) return 'not_running';
+  if (!deps.isProcessAlive(state.pid)) {
+    deps.removeState(paths.graphRuntimeStatePath);
+    return 'not_running';
+  }
+  if (!isLoopbackConsoleUrl(state.url) ||
+      !await deps.consoleHealth(state.url, state.pid, state.version)) {
+    return 'unverified';
+  }
+
+  deps.stopProcess(state.pid);
+  if (!await deps.waitForExit(state.pid)) return 'still_running';
+  deps.removeState(paths.graphRuntimeStatePath);
+  return 'stopped';
+}
+
+function lifecycleDependencies(overrides) {
+  return {
+    readConfig: (path) => readJsonFile(path, null),
+    readState: safeReadState,
+    fileExists: existsSync,
+    ensureRuntime: ensureGraphRuntime,
+    stopProviders: stopGraphProviders,
+    consoleHealth: checkLocalConsoleHealth,
+    providerHealth,
+    isProcessAlive,
+    stopProcess,
+    waitForExit,
+    removeState: (path) => {
+      if (existsSync(path)) unlinkSync(path);
+    },
+    openExternal,
+    ...overrides
+  };
+}
+
+function safeReadState(path) {
+  try {
+    return readJsonFile(path, null);
+  } catch {
+    return null;
+  }
+}
+
+async function providerHealth(url) {
+  try {
+    const response = await fetch(`${String(url).replace(/\/$/, '')}/health`, {
+      signal: AbortSignal.timeout(2500)
+    });
+    if (!response.ok) return { url, status: 'unavailable' };
+    const body = await response.json();
+    return { url, status: body?.status === 'ready' ? 'ready' : 'unavailable' };
+  } catch {
+    return { url, status: 'unavailable' };
+  }
+}
+
+async function openExternal(url) {
+  const invocation = externalOpenInvocation(url);
+  const child = spawn(invocation.command, invocation.args, {
+    detached: true,
+    windowsHide: true,
+    stdio: 'ignore'
+  });
+  child.unref();
+}
+
+export function externalOpenInvocation(url, platform = process.platform) {
+  if (!isLoopbackConsoleUrl(url)) throw new TypeError('Only the local Fuli console can be opened');
+  if (platform === 'darwin') return { command: 'open', args: [url] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', url] };
+  return { command: 'xdg-open', args: [url] };
+}
+
+function hasManagedDevelopmentWorkspace(config) {
+  return (config?.workspaces ?? []).some(({ providerUrl }) =>
+    isManagedDevelopmentUrl(providerUrl));
+}
+
+function isManagedDevelopmentUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' &&
+      ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname) &&
+      url.port === new URL(MANAGED_WORKSPACE_PROVIDER_URL).port;
+  } catch {
+    return false;
+  }
+}
+
+function isLoopbackConsoleUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' &&
+      ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname) &&
+      url.username === '' && url.password === '' &&
+      (url.pathname === '/' || url.pathname === '') && !url.search && !url.hash;
+  } catch {
+    return false;
+  }
+}
+
+function publicProviderStatus(workspaces) {
+  if (!workspaces.length) return 'not_connected';
+  const ready = workspaces.filter(({ status }) => status === 'ready').length;
+  if (ready === workspaces.length) return 'ready';
+  return ready > 0 ? 'degraded' : 'unavailable';
+}
+
+function isRuntimeState(state) {
+  return (state?.version === 2 || state?.version === 3) &&
+    Number.isInteger(state.pid) && typeof state.url === 'string';
+}
+
+function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function stopProcess(pid) {
+  try { process.kill(pid, 'SIGTERM'); } catch { /* already stopped */ }
+}
+
+async function waitForExit(pid) {
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return false;
+}

package/src/mcp/create-mcp-server.js

@@ -0,0 +1,85 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { callAgentTool, listAgentTools } from '../agent-tools.js';
+import { FULI_VERSION } from '../package-metadata.js';
+import { MCP_INSTRUCTIONS } from './instructions.js';
+import { createProjectActionPreviewTokens } from './project-action-preview-tokens.js';
+import { annotationsFor } from './tool-annotations.js';
+import { errorToolResult, protocolErrorResult, successToolResult } from './tool-result.js';
+import { jsonSchemaToZod, openObjectSchema } from './tool-schema.js';
+
+const TOOL_RESULT_LIMIT_BYTES = Object.freeze({
+  get_collaboration_preferences: 16 * 1024,
+  search_knowledge_graph: 32 * 1024
+});
+
+export function createMcpServer(app) {
+  const server = new McpServer(
+    { name: 'fuli', version: FULI_VERSION },
+    { instructions: MCP_INSTRUCTIONS }
+  );
+
+  const tools = createToolMap(app, createProjectActionPreviewTokens());
+  for (const tool of tools.values()) registerTool(server, tool);
+  registerCallHandler(server, tools);
+  return server;
+}
+
+function createToolMap(app, projectActionPreviews) {
+  return new Map(listAgentTools().map((definition) => [definition.name, {
+    definition,
+    schema: jsonSchemaToZod(definition.inputSchema),
+    invoke: (input) => invokeAgentTool(
+      app,
+      definition.name,
+      input,
+      projectActionPreviews
+    )
+  }]));
+}
+
+function registerTool(server, tool) {
+  const { definition, schema } = tool;
+  server.registerTool(definition.name, {
+    title: definition.title,
+    description: definition.description,
+    inputSchema: schema,
+    outputSchema: openObjectSchema(),
+    annotations: annotationsFor(definition.name)
+  }, (input) => invokeTool(tool, input));
+}
+
+function registerCallHandler(server, tools) {
+  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.get(request.params.name);
+    if (!tool) return errorToolResult(new Error('Unknown tool'));
+    const parsed = await tool.schema.safeParseAsync(request.params.arguments ?? {});
+    if (!parsed.success) return protocolErrorResult('Input validation error');
+    return invokeTool(tool, parsed.data);
+  });
+}
+
+async function invokeTool(tool, input) {
+  try {
+    return successToolResult(await tool.invoke(input), {
+      limitBytes: TOOL_RESULT_LIMIT_BYTES[tool.definition.name]
+    });
+  } catch (error) {
+    return errorToolResult(error);
+  }
+}
+
+async function invokeAgentTool(app, name, input, projectActionPreviews) {
+  if (name === 'preview_personal_project_action') {
+    const result = await callAgentTool(app, name, input);
+    return {
+      ...result,
+      previewToken: projectActionPreviews.issue(input)
+    };
+  }
+  if (name === 'apply_personal_project_action') {
+    projectActionPreviews.consume(input.previewToken, input);
+  }
+  return callAgentTool(app, name, input);
+}

package/src/mcp/instructions.js

@@ -0,0 +1,10 @@
+export const MCP_INSTRUCTIONS = [
+  "Each user task: call exactly get_collaboration_preferences before other tools/answer with projectPath=cwd; never substitute a project action or Fuli tool. Apply all effective_preferences: personal-global everywhere plus only Fuli's matched project. Resolve relevant deferred_conflict via resolve_deferred_preference_conflict; ignore others. Pending is search-only. Never guess personalProjectId. Writes must enforce preferences in the actual payload; final text is not compliance.",
+  'Before claiming URLs, routes, requirements, prior decisions, or runbooks are unknown, call search_knowledge_graph; resolve IDs via list_knowledge_spaces/list_personal_projects.',
+  'Search personal-global profile, exact personalProjectId, inheritable knowledge reached via PART_OF or USES_KNOWLEDGE_FROM, named contextPersonalProjectIds, and relevant subscribed public project IDs. Never inherit project preferences or traverse RELATED_TO. Pending results stay marked. On a location miss, ask to widen to all registered local personal projects; use all_local_confirmed only after explicit confirmation. It never expands public projects.',
+  'After a confirmed all-local miss, search current repository or workspace files with Grep or rg. Never scan user home, filesystem root, outside the workspace, credentials, browser data, or unrelated repositories. Require deployment evidence for live URLs.',
+  'Changing/live: use monitoring or Git MCP',
+  'Silently batch via capture_session_knowledge under personalProjectId. Never store secrets, transcripts, or guesses. Only human/source confirmed knowledge enters public review. Final checkpoint: flush or retain nothing.',
+  'When personal knowledge affects the final answer/action, call record_knowledge_usage. Retrieval/injection never count; it creates at most agent_confirmed, never public eligibility.',
+  'Searches return terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown and append sourceMarker.markdown unchanged; without support use noMatchSourceMarker. Never wrap markers in HTML, rewrite them, or cite writes as reads.'
+].join(' ');

package/src/mcp/project-action-preview-tokens.js

@@ -0,0 +1,72 @@
+import { randomUUID } from 'node:crypto';
+
+import { ApplicationError } from '../app/application-error.js';
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+export function createProjectActionPreviewTokens({
+  now = Date.now,
+  createToken = randomUUID,
+  ttlMs = DEFAULT_TTL_MS
+} = {}) {
+  const previews = new Map();
+
+  return Object.freeze({
+    issue(input) {
+      pruneExpired(previews, now());
+      const token = createToken();
+      previews.set(token, {
+        expiresAt: now() + ttlMs,
+        intent: projectActionIntent(input)
+      });
+      return token;
+    },
+
+    consume(token, input) {
+      if (!token) {
+        throw new ApplicationError(
+          'preview_required',
+          'Preview this exact project action before applying it'
+        );
+      }
+      const preview = previews.get(token);
+      if (!preview || preview.expiresAt <= now()) {
+        previews.delete(token);
+        throw new ApplicationError(
+          'preview_expired',
+          'Project action preview authorization is missing or expired'
+        );
+      }
+      if (preview.intent !== projectActionIntent(input)) {
+        throw new ApplicationError(
+          'preview_mismatch',
+          'Project action no longer matches its preview'
+        );
+      }
+      previews.delete(token);
+    }
+  });
+}
+
+function projectActionIntent(input) {
+  return JSON.stringify({
+    personalSpaceId: input.personalSpaceId,
+    itemKind: input.itemKind,
+    itemId: input.itemId,
+    mode: input.mode,
+    targetProjectId: input.targetProjectId ?? null,
+    newProjectId: input.newProjectId ?? null,
+    newProjectName: input.newProjectName ?? null,
+    newProjectPurpose: input.newProjectPurpose ?? null,
+    keepSourceRelation: input.keepSourceRelation ?? true,
+    relationType: input.relationType ?? 'RELATED_TO',
+    conflictResolution: input.conflictResolution ?? 'defer',
+    reason: input.reason
+  });
+}
+
+function pruneExpired(previews, currentTime) {
+  for (const [token, preview] of previews) {
+    if (preview.expiresAt <= currentTime) previews.delete(token);
+  }
+}

package/src/mcp/runtime.js

@@ -0,0 +1,71 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { openFederatedGraphApplication } from '../graphiti/federated-application.js';
+import { createMcpServer } from './create-mcp-server.js';
+
+export async function runStdio({ runtimeConfigPath }) {
+  const app = openFederatedGraphApplication({ runtimeConfigPath });
+  const server = createServerOrClose(app);
+  const transport = new StdioServerTransport();
+  const signalHandlers = new Map();
+  const close = createCloseOnce({
+    closeServer: () => server.close(),
+    closeApplication: () => app.close(),
+    afterClose: () => removeHandlers(signalHandlers)
+  });
+  const quietClose = createQuietCloser(close, () => { process.exitCode = 1; });
+
+  server.server.onclose = quietClose;
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    const handler = quietClose;
+    signalHandlers.set(signal, handler);
+    process.once(signal, handler);
+  }
+  process.stdin.once('end', quietClose);
+
+  try {
+    await server.connect(transport);
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+
+export function createServerOrClose(app, factory = createMcpServer) {
+  try {
+    return factory(app);
+  } catch (error) {
+    void app.close();
+    throw error;
+  }
+}
+
+export function createCloseOnce({ closeServer, closeApplication, afterClose = () => {} }) {
+  let closing;
+  return () => {
+    if (!closing) {
+      closing = Promise.resolve().then(async () => {
+        try {
+          await closeServer();
+        } finally {
+          try {
+            await closeApplication();
+          } finally {
+            afterClose();
+          }
+        }
+      });
+    }
+    return closing;
+  };
+}
+
+export function createQuietCloser(close, onFailure = () => {}) {
+  return () => {
+    close().catch(onFailure);
+  };
+}
+
+function removeHandlers(signalHandlers) {
+  for (const [signal, handler] of signalHandlers) process.off(signal, handler);
+}

package/src/mcp/tool-annotations.js

@@ -0,0 +1,63 @@
+const READ_TOOLS = new Set([
+  'list_knowledge_spaces',
+  'list_personal_projects',
+  'preview_personal_project_action',
+  'list_project_releases',
+  'list_project_relations',
+  'list_personal_review_queue',
+  'list_project_review_queue',
+  'get_graphiti_status'
+]);
+
+const WRITE_TOOLS = new Set([
+  'get_collaboration_preferences',
+  'resolve_deferred_preference_conflict',
+  'capture_session_knowledge',
+  'search_knowledge_graph',
+  'record_knowledge_usage',
+  'get_knowledge_graph',
+  'search_human_knowledge_changes',
+  'review_human_knowledge_change',
+  'upsert_personal_project',
+  'revise_personal_knowledge',
+  'reassign_personal_knowledge',
+  'set_personal_preference_scope',
+  'apply_personal_project_action',
+  'publish_personal_project',
+  'create_project_relation',
+  'review_project_relation',
+  'review_personal_draft',
+  'subscribe_public_project',
+  'unsubscribe_public_project',
+  'review_project_proposal'
+]);
+
+const DESTRUCTIVE_TOOLS = new Set([
+  'resolve_deferred_preference_conflict',
+  'review_project_proposal',
+  'review_project_relation',
+  'review_personal_draft',
+  'unsubscribe_public_project'
+]);
+
+export function annotationsFor(name) {
+  if (!READ_TOOLS.has(name) && !WRITE_TOOLS.has(name)) {
+    throw new TypeError(`Missing MCP annotations for tool: ${name}`);
+  }
+  const readOnly = READ_TOOLS.has(name);
+  return {
+    readOnlyHint: readOnly,
+    destructiveHint: DESTRUCTIVE_TOOLS.has(name),
+    idempotentHint: readOnly || name === 'upsert_personal_project' ||
+      name === 'publish_personal_project' || name === 'unsubscribe_public_project' ||
+      name === 'record_knowledge_usage',
+    openWorldHint: name === 'capture_session_knowledge' ||
+      name === 'publish_personal_project' ||
+      name === 'create_project_relation' ||
+      name === 'review_project_relation' ||
+      name === 'review_personal_draft' ||
+      name === 'subscribe_public_project' ||
+      name === 'unsubscribe_public_project' ||
+      name === 'review_project_proposal'
+  };
+}