fuli-context 0.3.0 → 0.5.0

package/src/mcp/instructions.js

@@ -1,10 +1,9 @@
 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.',
+  "Each user task: if begin_task_context supplied hook-provided task context, apply. Otherwise call exactly get_collaboration_preferences with projectPath=cwd before other tools/answer as the fallback; 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 first. Never guess personalProjectId. Writes enforce preferences in the actual payload; final text is not compliance.",
+  'For current-project facts use search_current_project_knowledge: exact active child first, then inheritable parent knowledge via outgoing PART_OF/USES_KNOWLEDGE_FROM within two hops. Child stable keys override. Never inherit project preferences or traverse RELATED_TO.',
+  'Before claiming facts unknown, use search_knowledge_graph. Use exact IDs for extra projects; mark pending. Widen a location miss to all_local_confirmed only after consent, then use rg only in the safe current repo/workspace. Never scan outside it. Live URLs need deployment evidence; changing state needs monitoring/Git MCP.',
+  'Use record_decision_trace for confirmed choices/rationale/validation. Use record_knowledge_feedback when retained knowledge is rejected, contradicted, outdated, or fails validation; preserve history.',
+  'Batch durable confirmed knowledge via capture_session_knowledge in exact scope. Never store secrets, transcripts, or guesses. Only human/source confirmation permits public review. Finish a hook-managed task with checkpoint_task_knowledge once: capture_candidates or retain_nothing; fallback Agents likewise flush or retain nothing.',
+  'When personal knowledge materially affects the answer/action, call record_knowledge_usage. Retrieval/injection never counts; it creates at most agent_confirmed and is never public-eligible.',
   'Terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown; append sourceMarker.markdown unchanged only on match. On miss use noMatchSourceMarker leadMarkdown only (empty markdown). Never wrap markers in HTML or cite writes.'
 ].join(' ');

package/src/mcp/lifecycle-audit.js

@@ -0,0 +1,27 @@
+import { appendFileSync } from 'node:fs';
+
+const AUDITED_TOOLS = new Set([
+  'begin_task_context',
+  'checkpoint_task_knowledge',
+  'verify_task_checkpoint'
+]);
+
+export function auditLifecycleTool(
+  toolName,
+  {
+    auditPath = process.env.FULI_ACCEPTANCE_LIFECYCLE_AUDIT_PATH,
+    append = appendFileSync
+  } = {}
+) {
+  if (!auditPath || !AUDITED_TOOLS.has(toolName)) return false;
+  try {
+    append(
+      auditPath,
+      `${JSON.stringify({ event: toolName })}\n`,
+      { encoding: 'utf8', mode: 0o600 }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/mcp/task-context-registry.js

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto';
+
+const MAX_ACTIVE_SESSIONS = 256;
+
+export class TaskContextRegistry {
+  constructor({ tokenFactory = () => `fuli-task-${randomUUID()}` } = {}) {
+    this.tokenFactory = tokenFactory;
+    this.sessions = new Map();
+    this.tokens = new Map();
+  }
+
+  begin({ sessionId, personalProjectId }) {
+    assertNonEmpty(sessionId, 'sessionId');
+    const previous = this.sessions.get(sessionId) ?? null;
+    if (previous) this.tokens.delete(previous.token);
+
+    const task = {
+      token: this.tokenFactory(),
+      sessionId,
+      personalProjectId: personalProjectId ?? null,
+      checkpoint: null
+    };
+    this.sessions.delete(sessionId);
+    this.sessions.set(sessionId, task);
+    this.tokens.set(task.token, task);
+    this.#evictOldest();
+    return {
+      ...task,
+      previousCheckpointMissing: Boolean(previous && !previous.checkpoint)
+    };
+  }
+
+  checkpoint(token, checkpoint) {
+    assertNonEmpty(token, 'taskContextToken');
+    const task = this.tokens.get(token);
+    if (!task) throw new TypeError('Unknown or expired Fuli task context token');
+    if (task.checkpoint) {
+      if (sameCheckpoint(task.checkpoint, checkpoint)) return task;
+      throw new TypeError('Fuli task context has already been checkpointed');
+    }
+    task.checkpoint = Object.freeze({ ...checkpoint });
+    return task;
+  }
+
+  context(token) {
+    assertNonEmpty(token, 'taskContextToken');
+    const task = this.tokens.get(token);
+    if (!task) throw new TypeError('Unknown or expired Fuli task context token');
+    return task;
+  }
+
+  verify(sessionId) {
+    assertNonEmpty(sessionId, 'sessionId');
+    const task = this.sessions.get(sessionId);
+    if (!task) {
+      return {
+        status: 'not_started',
+        guidance: 'No Fuli task context was started; do not block the Agent.'
+      };
+    }
+    if (task.checkpoint) {
+      return {
+        status: 'checkpointed',
+        disposition: task.checkpoint.disposition
+      };
+    }
+    return {
+      status: 'checkpoint_required',
+      decision: 'block',
+      reason: 'Before finishing, call checkpoint_task_knowledge once with either a bounded durable candidate batch or retain_nothing. Do not store raw transcripts, guesses, or temporary output.'
+    };
+  }
+
+  #evictOldest() {
+    while (this.sessions.size > MAX_ACTIVE_SESSIONS) {
+      const [sessionId, task] = this.sessions.entries().next().value;
+      this.sessions.delete(sessionId);
+      this.tokens.delete(task.token);
+    }
+  }
+}
+
+function assertNonEmpty(value, label) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`${label} must be a nonempty string`);
+  }
+}
+
+function sameCheckpoint(left, right) {
+  return left.disposition === right.disposition
+    && left.reason === right.reason
+    && left.captureStatus === right.captureStatus;
+}

package/src/mcp/tool-annotations.js

@@ -1,4 +1,8 @@
 const READ_TOOLS = new Set([
+  'verify_task_checkpoint',
+  'search_current_project_knowledge',
+  'discover_common_knowledge_candidates',
+  'preview_common_knowledge_promotion',
   'list_knowledge_spaces',
   'list_personal_projects',
   'preview_personal_project_action',
@@ -10,11 +14,16 @@ const READ_TOOLS = new Set([
 ]);
 
 const WRITE_TOOLS = new Set([
+  'begin_task_context',
+  'checkpoint_task_knowledge',
   'get_collaboration_preferences',
   'resolve_deferred_preference_conflict',
   'capture_session_knowledge',
+  'record_decision_trace',
   'search_knowledge_graph',
   'record_knowledge_usage',
+  'record_knowledge_feedback',
+  'apply_common_knowledge_promotion',
   'get_knowledge_graph',
   'search_human_knowledge_changes',
   'review_human_knowledge_change',
@@ -34,6 +43,7 @@ const WRITE_TOOLS = new Set([
 
 const DESTRUCTIVE_TOOLS = new Set([
   'resolve_deferred_preference_conflict',
+  'apply_common_knowledge_promotion',
   'review_project_proposal',
   'review_project_relation',
   'review_personal_draft',
@@ -50,8 +60,13 @@ export function annotationsFor(name) {
     destructiveHint: DESTRUCTIVE_TOOLS.has(name),
     idempotentHint: readOnly || name === 'upsert_personal_project' ||
       name === 'publish_personal_project' || name === 'unsubscribe_public_project' ||
-      name === 'record_knowledge_usage',
+      name === 'record_knowledge_usage' || name === 'record_decision_trace' ||
+      name === 'record_knowledge_feedback' ||
+      name === 'checkpoint_task_knowledge',
     openWorldHint: name === 'capture_session_knowledge' ||
+      name === 'record_decision_trace' ||
+      name === 'record_knowledge_feedback' ||
+      name === 'checkpoint_task_knowledge' ||
       name === 'publish_personal_project' ||
       name === 'create_project_relation' ||
       name === 'review_project_relation' ||

package/src/mcp/tool-result.js

@@ -32,6 +32,30 @@ export function successToolResult(value, { limitBytes = RESULT_LIMIT_BYTES } = {
   };
 }
 
+export function hookAdditionalContextToolResult(
+  value,
+  {
+    hookEventName,
+    label,
+    limitBytes = RESULT_LIMIT_BYTES
+  }
+) {
+  const result = successToolResult(value, { limitBytes });
+  const additionalContext = `${label}\n${JSON.stringify(result.structuredContent)}`;
+  return {
+    ...result,
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName,
+          additionalContext
+        }
+      })
+    }]
+  };
+}
+
 export function errorToolResult(error) {
   const controlled = error instanceof ApplicationError;
   const code = controlled ? error.code : 'internal_error';

package/src/runtime-options.js

@@ -25,7 +25,7 @@ export function resolveRuntimeOptions(args = [], env = process.env, {
   let defaultDbPath = systemDbPath;
   if (cliDbPath === null && envDbPath === null) {
     defaultDbPath = resolveDefaultDbPath({ cwd, existsSync, systemDbPath });
-    guardImplicitDefaultUpgrade({ cwd, existsSync, systemDbPath });
+    guardImplicitDefaultUpgrade({ cwd, existsSync });
   }
   return {
     dbPath: cliDbPath ?? envDbPath ?? defaultDbPath,
@@ -36,8 +36,7 @@ export function resolveRuntimeOptions(args = [], env = process.env, {
 
 export function resolveStore({ dbPath }) {
   if (extname(dbPath).toLowerCase() === '.json') {
-    const destination = dbPath.slice(0, -extname(dbPath).length) + '.db';
-    throw new RuntimeConfigurationError(migrationMessage(dbPath, destination));
+    throw new RuntimeConfigurationError(legacyJsonMessage(dbPath));
   }
   return openSqliteStore(dbPath);
 }
@@ -59,17 +58,17 @@ function resolveDefaultDbPath({ cwd, existsSync, systemDbPath }) {
   return systemDbPath;
 }
 
-function guardImplicitDefaultUpgrade({ cwd, existsSync, systemDbPath }) {
+function guardImplicitDefaultUpgrade({ cwd, existsSync }) {
   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));
+    throw new RuntimeConfigurationError(legacyJsonMessage(legacyPath));
   }
 }
 
-function migrationMessage(source, destination) {
-  return 'JSON is a legacy import format. Run once: node src/cli.js migrate ' +
-    `--from ${quoteShellArgument(source)} --to ${quoteShellArgument(destination)}`;
+function legacyJsonMessage(source) {
+  return `JSON is a retired legacy format (${quoteShellArgument(source)}). ` +
+    'The current Fuli CLI no longer provides SQLite knowledge commands or JSON migration.';
 }
 
 export function openLocalApplication({ dbPath, personalSpaceName = DEFAULT_PERSONAL_SPACE }) {

package/src/server/lan-access.js

@@ -0,0 +1,52 @@
+import { isIPv4 } from 'node:net';
+import { networkInterfaces } from 'node:os';
+
+export const LAN_ACCESS_USERNAME = 'fuli';
+
+export function discoverLanAddresses(interfaces = networkInterfaces()) {
+  const addresses = [];
+  for (const entries of Object.values(interfaces ?? {})) {
+    for (const entry of entries ?? []) {
+      if (!entry || entry.internal || !isIpv4Family(entry.family)) continue;
+      if (!isPrivateLanIpv4(entry.address)) continue;
+      addresses.push(entry.address);
+    }
+  }
+  return [...new Set(addresses)].sort(compareIpv4);
+}
+
+export function lanConsoleUrls(addresses, port) {
+  return addresses.map((address) => `http://${consoleAuthority(address, port)}`);
+}
+
+export function lanServerAuthorities(addresses, port) {
+  return lanConsoleUrls(addresses, port).map((url) => new URL(url).host);
+}
+
+function isIpv4Family(family) {
+  return family === 'IPv4' || family === 4;
+}
+
+function isPrivateLanIpv4(address) {
+  if (!isIPv4(address)) return false;
+  const [first, second] = address.split('.').map(Number);
+  return first === 10 ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168) ||
+    (first === 169 && second === 254);
+}
+
+function consoleAuthority(address, port) {
+  return Number(port) === 80 ? address : `${address}:${port}`;
+}
+
+function compareIpv4(left, right) {
+  const leftParts = left.split('.').map(Number);
+  const rightParts = right.split('.').map(Number);
+  for (let index = 0; index < 4; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] - rightParts[index];
+    }
+  }
+  return 0;
+}

package/src/server.js

@@ -4,11 +4,16 @@ 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 { localServerAuthority, rejectRequestOutsidePolicy } 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 {
+  discoverLanAddresses,
+  lanConsoleUrls,
+  lanServerAuthorities
+} from './server/lan-access.js';
 import { createServerApplication } from './server/application-lifecycle.js';
 import { listenServer } from './server/listen.js';
 
@@ -26,8 +31,19 @@ export async function createServer(options = {}) {
     store,
     app,
     closeApplicationOnShutdown,
-    isBlockedPort = isFetchBlockedPort
+    isBlockedPort = isFetchBlockedPort,
+    lan = false,
+    lanAccessToken = null,
+    lanAddresses: configuredLanAddresses = null
   } = options;
+  const lanEnabled = lan === true;
+  const lanToken = lanEnabled ? requiredLanToken(lanAccessToken) : null;
+  const lanAddresses = lanEnabled
+    ? [...new Set(configuredLanAddresses ?? discoverLanAddresses())]
+    : [];
+  if (lanEnabled && lanAddresses.length === 0) {
+    throw new Error('No private IPv4 LAN address is available');
+  }
   if (Number(port) !== 0 && isBlockedPort(port)) {
     throw new Error(`Port ${port} is blocked for local fetch`);
   }
@@ -45,15 +61,23 @@ export async function createServer(options = {}) {
 
   for (let attempt = 0; attempt < 20; attempt += 1) {
     let authority = null;
+    let allowedLanAuthorities = [];
     const server = createHttpServer((request, response) => {
-      handleRequest({ request, response, app: application, authority }).catch((error) => {
+      handleRequest({
+        request,
+        response,
+        app: application,
+        authority,
+        lanAuthorities: allowedLanAuthorities,
+        lanAccessToken: lanToken
+      }).catch((error) => {
         const mapped = mapHttpError(error);
         sendJson(response, mapped.status, mapped.body);
       });
     });
 
     try {
-      await listenServer(server, port);
+      await listenServer(server, port, lanEnabled ? '0.0.0.0' : '127.0.0.1');
     } catch (error) {
       runtime.close();
       throw error;
@@ -66,6 +90,9 @@ export async function createServer(options = {}) {
       throw new Error(`Port ${address.port} is blocked for local fetch`);
     }
     authority = localServerAuthority(address);
+    allowedLanAuthorities = lanEnabled
+      ? lanServerAuthorities(lanAddresses, address.port)
+      : [];
     if (!authority) {
       await new Promise((resolveClose) => server.close(resolveClose));
       runtime.close();
@@ -73,7 +100,12 @@ export async function createServer(options = {}) {
     }
 
     server.once('close', runtime.close);
-    return { server, url: `http://${authority}`, app: application };
+    return {
+      server,
+      url: `http://${authority}`,
+      lanUrls: lanEnabled ? lanConsoleUrls(lanAddresses, address.port) : [],
+      app: application
+    };
   }
 
   runtime.close();
@@ -94,8 +126,21 @@ export function isFetchBlockedPort(port) {
   return FETCH_BLOCKED_PORTS.has(Number(port));
 }
 
-async function handleRequest({ request, response, app, authority }) {
-  if (rejectDisallowedRequest({ request, response, authority })) return;
+async function handleRequest({
+  request,
+  response,
+  app,
+  authority,
+  lanAuthorities,
+  lanAccessToken
+}) {
+  if (rejectRequestOutsidePolicy({
+    request,
+    response,
+    authority,
+    lanAuthorities,
+    lanAccessToken
+  })) return;
   if (await handleApiRequest({ request, response, app })) return;
   serveStatic(new URL(request.url, 'http://127.0.0.1').pathname, response);
 }
@@ -110,7 +155,13 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[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 lan = args.includes('--lan');
+  const { server, url, lanUrls } = await createServer({
+    ...runtimeOptions,
+    port,
+    lan,
+    lanAccessToken: lan ? process.env.FULI_LAN_ACCESS_TOKEN : null
+  });
   const handlers = new Map();
   const close = () => server.close();
   for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -122,6 +173,14 @@ async function runProgram(args) {
     for (const [signal, handler] of handlers) process.off(signal, handler);
   });
   console.log(`复利工作台 running at ${url}`);
+  for (const lanUrl of lanUrls) console.log(`复利工作台 LAN at ${lanUrl}`);
+}
+
+function requiredLanToken(value) {
+  if (typeof value !== 'string' || value.length < 16) {
+    throw new TypeError('LAN mode requires a generated access token');
+  }
+  return value;
 }
 
 function numberOption(args, flag, fallback) {

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 
 import { replaceFuliTable } from './codex-config.js';
 import { isCodexBootstrapCurrent } from './codex-bootstrap.js';
+import { hasCurrentClaudeCodeHooks } from './claude-code-config.js';
 import { isSessionSkillCurrent } from './session-skill.js';
 import { readJsonFile } from '../storage/json-file.js';
 
@@ -27,9 +28,16 @@ export function inspectAgentInstallations(agents, context, {
       context,
       { fileExists, readText }
     );
+    const claudeLifecycleCurrent = agent.id !== 'claude-code' ||
+      hasCurrentClaudeCodeHooks(readJson(agent.settingsPath));
 
     let integrationStatus = 'not_connected';
-    if (registration.current && skillsCurrent && codexBootstrapCurrent) {
+    if (
+      registration.current
+      && skillsCurrent
+      && codexBootstrapCurrent
+      && claudeLifecycleCurrent
+    ) {
       integrationStatus = 'connected';
     }
     else if (registration.present || skillsPresent) integrationStatus = 'update_available';
@@ -42,6 +50,9 @@ export function inspectAgentInstallations(agents, context, {
         skills: skillsCurrent ? 'current' : skillsPresent ? 'outdated' : 'missing',
         ...(agent.id === 'codex'
           ? { bootstrap: codexBootstrapCurrent ? 'current' : 'outdated' }
+          : {}),
+        ...(agent.id === 'claude-code'
+          ? { lifecycleHooks: claudeLifecycleCurrent ? 'current' : 'outdated' }
           : {})
       }
     };
@@ -71,7 +82,8 @@ function inspectRegistration(agent, context, readers) {
       present,
       current: present &&
         server.command === expected.command &&
-        sameStrings(server.args, expected.args)
+        sameStrings(server.args, expected.args) &&
+        (agent.id !== 'claude-code' || server.alwaysLoad === true)
     };
   } catch {
     return { present: false, current: false };

package/src/setup/agents.js

@@ -3,6 +3,10 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 
+import {
+  connectClaudeCode,
+  disconnectClaudeCode
+} from './claude-code-config.js';
 import { connectCursor, disconnectCursor } from './cursor-config.js';
 import { connectCodex, disconnectCodex } from './codex-config.js';
 
@@ -34,6 +38,7 @@ export function discoverAgents({
       label: 'Claude Code',
       command: 'claude',
       configPath: pathApi.join(homeDir, '.claude.json'),
+      settingsPath: pathApi.join(homeDir, '.claude', 'settings.json'),
       skillPath: pathApi.join(homeDir, '.claude', 'skills', skillName),
       projectSkillPath: pathApi.join(homeDir, '.claude', 'skills', projectSkillName),
       available: Boolean(commandExists('claude'))
@@ -75,9 +80,13 @@ export function buildAgentCommands(agent, context) {
 export function connectAgent(agent, context, {
   runCommand = defaultRunCommand,
   connectCodexConfig = connectCodex,
+  connectClaudeCodeConfig = connectClaudeCode,
   connectCursorConfig = connectCursor
 } = {}) {
   if (agent.id === 'codex') return connectCodexConfig(agent, context);
+  if (agent.id === 'claude-code') {
+    return connectClaudeCodeConfig(agent, context);
+  }
   if (agent.id === 'cursor') return connectCursorConfig(agent, context);
 
   const commands = buildAgentCommands(agent, context);
@@ -91,10 +100,12 @@ export function connectAgent(agent, context, {
 
 export function disconnectAgent(agent, {
   disconnectCodexConfig = disconnectCodex,
+  disconnectClaudeCodeConfig = disconnectClaudeCode,
   disconnectJsonConfig = disconnectCursor
 } = {}) {
   if (agent.id === 'codex') return disconnectCodexConfig(agent);
-  if (agent.id === 'cursor' || agent.id === 'claude-code') {
+  if (agent.id === 'claude-code') return disconnectClaudeCodeConfig(agent);
+  if (agent.id === 'cursor') {
     return disconnectJsonConfig(agent);
   }
   throw new TypeError(`Unsupported agent: ${agent.id}`);