fuli-context 0.2.0

package/src/publication/publication-policy.js

@@ -0,0 +1,82 @@
+import {
+  FactScope,
+  FactStatus,
+  Sensitivity,
+  SpaceKind,
+  isCurrentFact
+} from '../models.js';
+import { detectSensitiveContent } from '../security/sensitive-content.js';
+import { canonicalJson } from './canonical-json.js';
+
+export function validatePublication(store, { spaceId, episode, facts }) {
+  const space = store.getSpace(spaceId);
+  if (!space || space.kind !== SpaceKind.PUBLIC) {
+    throw new Error(`Publication target must be a public space: ${spaceId}`);
+  }
+  if (!episode?.id) throw new Error('Publication source episode is required');
+
+  const storedEpisode = store.getEpisode(episode.id);
+  if (!storedEpisode) throw new Error(`Publication source episode not found: ${episode.id}`);
+  if (storedEpisode.spaceId !== spaceId) throw new Error('Publication episode crosses spaces');
+  assertAuthentic('episode', episode, storedEpisode);
+  assertNoSensitiveSource(storedEpisode);
+
+  if (!Array.isArray(facts) || facts.length === 0) {
+    throw new TypeError('Publication facts must be a non-empty array');
+  }
+  const factIds = facts.map((fact) => fact?.id);
+  if (new Set(factIds).size !== factIds.length) {
+    throw new TypeError('Publication facts contain a duplicate fact id');
+  }
+  const storedFacts = facts.map((fact) => validateFact(store, fact, spaceId, storedEpisode.id));
+  return { episode: storedEpisode, facts: storedFacts };
+}
+
+function validateFact(store, fact, spaceId, episodeId) {
+  if (!fact?.id) throw new Error('Publication fact is required');
+  const stored = store.getFact(fact.id);
+  if (!stored) throw new Error(`Publication fact not found: ${fact.id}`);
+  assertAuthentic('fact', fact, stored);
+  if (stored.spaceId !== spaceId) throw new Error('Publication fact crosses spaces');
+  if (stored.sourceEpisodeId !== episodeId) throw new Error('Publication fact has missing source');
+  if (stored.scope !== FactScope.PUBLIC) throw new Error('Personal facts cannot be published');
+  if (stored.status !== FactStatus.CONFIRMED) throw new Error('Publication fact is not confirmed');
+  if (stored.sensitivity !== Sensitivity.NORMAL) {
+    throw new Error('Private or restricted facts cannot be published');
+  }
+  if (!isCurrentFact(stored) || !store.currentFacts(spaceId).some(({ id }) => id === stored.id)) {
+    throw new Error('Historical facts cannot be published');
+  }
+  assertSafeTexts([stored.subject, stored.predicate, stored.object]);
+  return stored;
+}
+
+function assertAuthentic(label, supplied, stored) {
+  if (canonicalJson(supplied) !== canonicalJson(stored)) {
+    throw new Error(`Publication ${label} does not match stored record`);
+  }
+}
+
+function assertNoSensitiveSource(episode) {
+  assertSafeTexts([
+    episode.body,
+    episode.sourceKind,
+    episode.sourceUri,
+    ...metadataStrings(episode.metadata)
+  ]);
+}
+
+function assertSafeTexts(texts) {
+  if (texts.some((text) => detectSensitiveContent(text).restricted)) {
+    throw new Error('Detected secret cannot be published');
+  }
+}
+
+function metadataStrings(value) {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.flatMap(metadataStrings);
+  if (value && typeof value === 'object') {
+    return Object.entries(value).flatMap(([key, item]) => [key, ...metadataStrings(item)]);
+  }
+  return [];
+}

package/src/publication/publication-service.js

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+
+import { createEnvelope, verifyEnvelope } from './publication-envelope.js';
+import { validatePublication } from './publication-policy.js';
+
+export class PublicationService {
+  constructor(store, { id = randomUUID } = {}) {
+    this.store = store;
+    this.id = id;
+  }
+
+  prepare(input) {
+    validatePublication(this.store, input);
+    return this.store.transaction(
+      () => this.#validateBuildAndEnqueue(input),
+      { mode: 'immediate' }
+    );
+  }
+
+  prepareInCurrentTransaction(input) {
+    return this.#validateBuildAndEnqueue(input);
+  }
+
+  verify(envelope) {
+    return verifyEnvelope(envelope);
+  }
+
+  #validateBuildAndEnqueue(input) {
+    const records = validatePublication(this.store, input);
+    return this.#enqueue({
+      spaceId: input.spaceId,
+      envelope: createEnvelope({
+        id: this.id(),
+        spaceId: input.spaceId,
+        ...records
+      })
+    });
+  }
+
+  #enqueue({ spaceId, envelope }) {
+    const outbox = this.store.enqueueOutbox({
+      kind: 'publication',
+      aggregateId: `${spaceId}:${envelope.id}`,
+      payload: { envelope }
+    });
+    return { envelope, outbox };
+  }
+}

package/src/router.js

@@ -0,0 +1,58 @@
+import { isCurrentFact } from './models.js';
+
+export class ContextRouter {
+  constructor(store) {
+    this.store = store;
+  }
+
+  searchContext({ personalSpaceId, query, includeHistorical = false }) {
+    const spaceIds = [
+      personalSpaceId,
+      ...this.store.subscriptionsFor(personalSpaceId).map((subscription) => subscription.spaceId)
+    ];
+    const facts = this.store.searchFacts(spaceIds, query, { includeHistorical });
+    const matches = facts.map((fact) => buildMatch(this.store, fact));
+
+    return {
+      query,
+      spaceIds,
+      matches,
+      facts,
+      answer: formatAnswer(facts)
+    };
+  }
+}
+
+function buildMatch(store, fact) {
+  const episode = store.getEpisode(fact.sourceEpisodeId);
+
+  return {
+    spaceId: fact.spaceId,
+    spaceName: store.getSpace(fact.spaceId)?.name ?? fact.spaceId,
+    current: isCurrentFact(fact),
+    fact,
+    source: episode
+      ? {
+          id: episode.id,
+          kind: episode.sourceKind,
+          uri: episode.sourceUri,
+          body: episode.body,
+          createdAt: episode.createdAt
+        }
+      : null
+  };
+}
+
+function formatAnswer(facts) {
+  if (facts.length === 0) {
+    return '没有找到相关当前事实';
+  }
+
+  return facts
+    .map((fact) => `${fact.subject}：${humanPredicate(fact.predicate)} 是 ${fact.object}`)
+    .join('\n');
+}
+
+function humanPredicate(predicate) {
+  return predicate.startsWith('has_') ? predicate.slice(4) : predicate;
+}

package/src/runtime-options.js

@@ -0,0 +1,139 @@
+import { existsSync as fileExistsSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+
+import { createApplication } from './app/create-application.js';
+import { SpaceKind } from './models.js';
+import { resolveSetupPaths } from './setup/paths.js';
+import { SqliteStore } from './storage/sqlite-store.js';
+
+const LEGACY_LOCAL_DB_PATH = '.fuli/context.db';
+const DEFAULT_PERSONAL_SPACE = '我';
+const RETRY_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+const RETRY_DELAY_MS = 5;
+const STORE_OPEN_TIMEOUT_MS = 5000;
+
+export class RuntimeConfigurationError extends TypeError {}
+
+export function resolveRuntimeOptions(args = [], env = process.env, {
+  cwd = process.cwd(),
+  existsSync = fileExistsSync,
+  setupPaths = {}
+} = {}) {
+  const cliDbPath = runtimeValue(args, '--db');
+  const envDbPath = environmentValue(env, 'FULI_DB_PATH');
+  const systemDbPath = resolveSetupPaths({ env, ...setupPaths }).dbPath;
+  let defaultDbPath = systemDbPath;
+  if (cliDbPath === null && envDbPath === null) {
+    defaultDbPath = resolveDefaultDbPath({ cwd, existsSync, systemDbPath });
+    guardImplicitDefaultUpgrade({ cwd, existsSync, systemDbPath });
+  }
+  return {
+    dbPath: cliDbPath ?? envDbPath ?? defaultDbPath,
+    personalSpaceName: runtimeValue(args, '--personal-space') ??
+      environmentValue(env, 'FULI_PERSONAL_SPACE') ?? DEFAULT_PERSONAL_SPACE
+  };
+}
+
+export function resolveStore({ dbPath }) {
+  if (extname(dbPath).toLowerCase() === '.json') {
+    const destination = dbPath.slice(0, -extname(dbPath).length) + '.db';
+    throw new RuntimeConfigurationError(migrationMessage(dbPath, destination));
+  }
+  return openSqliteStore(dbPath);
+}
+
+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("'", "'\\''")}'`;
+}
+
+function resolveDefaultDbPath({ cwd, existsSync, systemDbPath }) {
+  if (existsSync(systemDbPath)) return systemDbPath;
+  if (existsSync(resolve(cwd, LEGACY_LOCAL_DB_PATH))) return LEGACY_LOCAL_DB_PATH;
+  return systemDbPath;
+}
+
+function guardImplicitDefaultUpgrade({ cwd, existsSync, systemDbPath }) {
+  const legacyPath = resolve(cwd, '.fuli/context.json');
+  const localDatabasePath = resolve(cwd, LEGACY_LOCAL_DB_PATH);
+  if (existsSync(legacyPath) && !existsSync(localDatabasePath)) {
+    throw new RuntimeConfigurationError(migrationMessage(legacyPath, systemDbPath));
+  }
+}
+
+function migrationMessage(source, destination) {
+  return 'JSON is a legacy import format. Run once: node src/cli.js migrate ' +
+    `--from ${quoteShellArgument(source)} --to ${quoteShellArgument(destination)}`;
+}
+
+export function openLocalApplication({ dbPath, personalSpaceName = DEFAULT_PERSONAL_SPACE }) {
+  const store = resolveStore({ dbPath });
+  const app = createApplication({ store, activePersonalSpaceName: personalSpaceName });
+  try {
+    initializeLocalSpaces(app, store, personalSpaceName);
+    return app;
+  } catch (error) {
+    app.close();
+    throw error;
+  }
+}
+
+export function initializeLocalSpaces(app, store, personalSpaceName) {
+  return store.transaction(() => {
+    if (store.listSpaces().length === 0) {
+      if (personalSpaceName === DEFAULT_PERSONAL_SPACE) {
+        app.bootstrap();
+      } else {
+        const personal = app.createSpace(personalSpaceName, SpaceKind.PERSONAL);
+        const project = app.createSpace('工作', SpaceKind.PUBLIC);
+        app.subscribe(personal.id, project.id);
+      }
+    }
+    return app.requireActivePersonalSpace();
+  }, { mode: 'immediate' });
+}
+
+function runtimeValue(args, flag) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== flag) continue;
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new TypeError(`Missing value for ${flag}`);
+    }
+    values.push(value);
+  }
+  if (values.length > 1) throw new TypeError(`Duplicate ${flag}`);
+  return values[0] ?? null;
+}
+
+function environmentValue(env, name) {
+  const value = env?.[name];
+  if (value === undefined) return null;
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`${name} must not be empty`);
+  }
+  return value;
+}
+
+function openSqliteStore(dbPath) {
+  const deadline = Date.now() + STORE_OPEN_TIMEOUT_MS;
+  while (true) {
+    try {
+      return new SqliteStore(dbPath);
+    } catch (error) {
+      if (!isDatabaseBusy(error) || Date.now() >= deadline) throw error;
+      Atomics.wait(RETRY_BUFFER, 0, 0, RETRY_DELAY_MS);
+    }
+  }
+}
+
+function isDatabaseBusy(error) {
+  return error?.code === 'SQLITE_BUSY' || error?.code === 'SQLITE_LOCKED';
+}

package/src/security/episode-visibility.js

@@ -0,0 +1,14 @@
+import { detectSensitiveContent } from './sensitive-content.js';
+
+export function isRestrictedEpisode(episode) {
+  return [
+    episode.sourceKind,
+    episode.body,
+    episode.sourceUri,
+    JSON.stringify(episode.metadata)
+  ].some(hasSensitiveContent);
+}
+
+function hasSensitiveContent(text) {
+  return detectSensitiveContent(text).restricted;
+}

package/src/security/fact-visibility.js

@@ -0,0 +1,15 @@
+import { Sensitivity } from '../models.js';
+import { detectSensitiveContent } from './sensitive-content.js';
+
+export function isRestrictedFact(fact) {
+  return fact.sensitivity === Sensitivity.RESTRICTED ||
+    [
+      fact.subject,
+      fact.predicate,
+      fact.object
+    ].some(hasSensitiveContent);
+}
+
+function hasSensitiveContent(text) {
+  return detectSensitiveContent(text).restricted;
+}

package/src/security/sensitive-content.js

@@ -0,0 +1,18 @@
+const DETECTORS = [
+  ['private_key', /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/i],
+  ['api_key', /\b(?:sk-[A-Za-z0-9_-]{12,}|sk_(?:live|test)_[A-Za-z0-9]{12,}|rk_(?:live|test)_[A-Za-z0-9]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|npm_[A-Za-z0-9]{20,}|AKIA[A-Z0-9]{16}|ASIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]{20,}|AIza[A-Za-z0-9_-]{20,}|ya29\.[A-Za-z0-9_-]{20,}|SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{32,})\b/],
+  ['aws_credential_assignment', /\bAWS_(?:SECRET_ACCESS_KEY|SESSION_TOKEN)\s*[:=]\s*(?:"[^"]{16,}"|'[^']{16,}'|[A-Za-z0-9/+=]{16,})/i],
+  ['bearer_token', /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/i],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/],
+  ['credential_assignment', /\b(?:password|passwd|passphrase|secret|api[-_ ]?key)\b\s*[:=]\s*(?:"[^"]+"|'[^']+'|[^\s,]+)/i],
+  ['token_assignment', /\b(?:access[-_ ]?token|auth[-_ ]?token|token)\b\s*[:=]\s*(?:"[^"]{16,}"|'[^']{16,}'|[A-Za-z0-9._~+/=-]{16,})/i]
+];
+
+export function detectSensitiveContent(text) {
+  if (typeof text !== 'string') return { restricted: false, reasons: [] };
+
+  const reasons = DETECTORS
+    .filter(([, pattern]) => pattern.test(text))
+    .map(([reason]) => reason);
+  return { restricted: reasons.length > 0, reasons };
+}

package/src/security/source-metadata-policy.js

@@ -0,0 +1,8 @@
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+import { detectSensitiveContent } from './sensitive-content.js';
+
+export function assertSafeSourceMetadata(sourceKind, sourceUri, errorMessage) {
+  if ([sourceKind, sourceUri].some((text) => detectSensitiveContent(text).restricted)) {
+    throw new ApplicationError(ApplicationErrorCode.VALIDATION, errorMessage);
+  }
+}

package/src/server/application-lifecycle.js

@@ -0,0 +1,34 @@
+import { createApplication } from '../app/create-application.js';
+import { openFederatedGraphApplication } from '../graphiti/federated-application.js';
+import { openLocalApplication } from '../runtime-options.js';
+
+export function createServerApplication({
+  app,
+  store,
+  dbPath,
+  runtimeConfigPath,
+  personalSpaceName,
+  closeApplicationOnShutdown
+}) {
+  const application = app ?? (store
+    ? createApplication({ store, activePersonalSpaceName: personalSpaceName })
+    : dbPath
+      ? openLocalApplication({ dbPath, personalSpaceName })
+      : openFederatedGraphApplication({ runtimeConfigPath }));
+  const owned = closeApplicationOnShutdown ?? (!app && !store);
+  return {
+    application,
+    close: closeOnce(() => {
+      if (owned) return application.close();
+    })
+  };
+}
+
+export function closeOnce(close) {
+  let closed = false;
+  return () => {
+    if (closed) return;
+    closed = true;
+    return close();
+  };
+}

package/src/server/listen.js

@@ -0,0 +1,24 @@
+export function listenServer(server, port, host = '127.0.0.1') {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      server.off('error', onError);
+      server.off('listening', onListening);
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    try {
+      server.listen(port, host);
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+}

package/src/server.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { createServer as createHttpServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+import { handleApiRequest } from './http/api-router.js';
+import { mapHttpError } from './http/error-mapping.js';
+import { localServerAuthority, rejectDisallowedRequest } from './http/request-policy.js';
+import { sendJson } from './http/response.js';
+import { serveStatic } from './http/static-handler.js';
+import { DEFAULT_FULI_PORT } from './defaults.js';
+import { resolveGraphRuntimeOptions } from './graphiti/runtime-config.js';
+import { createServerApplication } from './server/application-lifecycle.js';
+import { listenServer } from './server/listen.js';
+
+const FETCH_BLOCKED_PORTS = new Set([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+  103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
+  512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
+  995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668,
+  6669, 6697, 10080
+]);
+
+export async function createServer(options = {}) {
+  const {
+    port = DEFAULT_FULI_PORT,
+    store,
+    app,
+    closeApplicationOnShutdown,
+    isBlockedPort = isFetchBlockedPort
+  } = options;
+  if (Number(port) !== 0 && isBlockedPort(port)) {
+    throw new Error(`Port ${port} is blocked for local fetch`);
+  }
+  const legacyRuntime = app || store || Object.hasOwn(options, 'dbPath');
+  const localOptions = legacyRuntime
+    ? { dbPath: options.dbPath, personalSpaceName: options.personalSpaceName ?? '我' }
+    : resolveServerGraphOptions(options);
+  const runtime = createServerApplication({
+    app,
+    store,
+    ...localOptions,
+    closeApplicationOnShutdown
+  });
+  const application = runtime.application;
+
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    let authority = null;
+    const server = createHttpServer((request, response) => {
+      handleRequest({ request, response, app: application, authority }).catch((error) => {
+        const mapped = mapHttpError(error);
+        sendJson(response, mapped.status, mapped.body);
+      });
+    });
+
+    try {
+      await listenServer(server, port);
+    } catch (error) {
+      runtime.close();
+      throw error;
+    }
+    const address = server.address();
+    if (isBlockedPort(address.port)) {
+      await new Promise((resolveClose) => server.close(resolveClose));
+      if (Number(port) === 0) continue;
+      runtime.close();
+      throw new Error(`Port ${address.port} is blocked for local fetch`);
+    }
+    authority = localServerAuthority(address);
+    if (!authority) {
+      await new Promise((resolveClose) => server.close(resolveClose));
+      runtime.close();
+      throw new Error('Server did not bind to a valid local authority');
+    }
+
+    server.once('close', runtime.close);
+    return { server, url: `http://${authority}`, app: application };
+  }
+
+  runtime.close();
+  throw new Error('Could not find a fetchable local port');
+}
+
+function resolveServerGraphOptions(options) {
+  const args = [];
+  if (Object.hasOwn(options, 'runtimeConfigPath')) {
+    args.push('--runtime-config', options.runtimeConfigPath);
+  }
+  return resolveGraphRuntimeOptions(args, options.env ?? process.env, {
+    setupPaths: { homeDir: options.homeDir, cwd: options.cwd ?? process.cwd() }
+  });
+}
+
+export function isFetchBlockedPort(port) {
+  return FETCH_BLOCKED_PORTS.has(Number(port));
+}
+
+async function handleRequest({ request, response, app, authority }) {
+  if (rejectDisallowedRequest({ request, response, authority })) return;
+  if (await handleApiRequest({ request, response, app })) return;
+  serveStatic(new URL(request.url, 'http://127.0.0.1').pathname, response);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runProgram(process.argv.slice(2)).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}
+
+async function runProgram(args) {
+  const runtimeOptions = resolveGraphRuntimeOptions(args, process.env);
+  const port = numberOption(args, '--port', DEFAULT_FULI_PORT);
+  const { server, url } = await createServer({ ...runtimeOptions, port });
+  const handlers = new Map();
+  const close = () => server.close();
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    const handler = close;
+    handlers.set(signal, handler);
+    process.once(signal, handler);
+  }
+  server.once('close', () => {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  });
+  console.log(`复利工作台 running at ${url}`);
+}
+
+function numberOption(args, flag, fallback) {
+  const index = args.indexOf(flag);
+  if (index === -1) return fallback;
+  const value = args[index + 1];
+  if (!value || value.startsWith('--') || !Number.isFinite(Number(value))) {
+    throw new TypeError(`Missing or invalid value for ${flag}`);
+  }
+  return Number(value);
+}

package/src/setup/agent-installation-status.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+import { replaceFuliTable } from './codex-config.js';
+import { isCodexBootstrapCurrent } from './codex-bootstrap.js';
+import { isSessionSkillCurrent } from './session-skill.js';
+import { readJsonFile } from '../storage/json-file.js';
+
+export function inspectAgentInstallations(agents, context, {
+  readText = defaultReadText,
+  readJson = defaultReadJson,
+  fileExists = existsSync,
+  skillCurrent = isSessionSkillCurrent,
+  bootstrapCurrent = isCodexBootstrapCurrent
+} = {}) {
+  return agents.map((agent) => {
+    const registration = inspectRegistration(agent, context, { readText, readJson });
+    const skillPairs = [
+      [context.sessionSkillPath, agent.skillPath],
+      [context.projectSkillPath, agent.projectSkillPath]
+    ];
+    const skillsPresent = skillPairs.some(([, targetPath]) => fileExists(targetPath));
+    const skillsCurrent = skillPairs.every(
+      ([sourcePath, targetPath]) => skillCurrent(sourcePath, targetPath)
+    );
+    const codexBootstrapCurrent = agent.id !== 'codex' || bootstrapCurrent(
+      agent,
+      context,
+      { fileExists, readText }
+    );
+
+    let integrationStatus = 'not_connected';
+    if (registration.current && skillsCurrent && codexBootstrapCurrent) {
+      integrationStatus = 'connected';
+    }
+    else if (registration.present || skillsPresent) integrationStatus = 'update_available';
+
+    return {
+      ...agent,
+      integrationStatus,
+      integrationDetails: {
+        mcp: registration.current ? 'current' : registration.present ? 'outdated' : 'missing',
+        skills: skillsCurrent ? 'current' : skillsPresent ? 'outdated' : 'missing',
+        ...(agent.id === 'codex'
+          ? { bootstrap: codexBootstrapCurrent ? 'current' : 'outdated' }
+          : {})
+      }
+    };
+  });
+}
+
+function inspectRegistration(agent, context, readers) {
+  const expected = {
+    command: context.nodePath,
+    args: [context.mcpServerPath, '--runtime-config', context.runtimeConfigPath]
+  };
+  try {
+    if (agent.id === 'codex') {
+      const current = readers.readText(agent.configPath);
+      const present = /^\s*\[mcp_servers\.(?:fuli|"fuli"|'fuli')]/m.test(current);
+      return {
+        present,
+        current: present && normalizeText(replaceFuliTable(current, expected)) ===
+          normalizeText(current)
+      };
+    }
+
+    const config = readers.readJson(agent.configPath);
+    const server = config?.mcpServers?.fuli;
+    const present = Boolean(server && typeof server === 'object' && !Array.isArray(server));
+    return {
+      present,
+      current: present &&
+        server.command === expected.command &&
+        sameStrings(server.args, expected.args)
+    };
+  } catch {
+    return { present: false, current: false };
+  }
+}
+
+function sameStrings(actual, expected) {
+  return Array.isArray(actual) &&
+    actual.length === expected.length &&
+    actual.every((value, index) => value === expected[index]);
+}
+
+function normalizeText(value) {
+  return value.replaceAll('\r\n', '\n').trim();
+}
+
+function defaultReadText(path) {
+  return existsSync(path) ? readFileSync(path, 'utf8') : '';
+}
+
+function defaultReadJson(path) {
+  return readJsonFile(path, {});
+}