fuli-context 0.7.6 → 0.7.7

package/src/mcp/session-id.js

@@ -3,11 +3,20 @@ import { randomUUID } from 'node:crypto';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const WORKFLOW_OBSERVATION_TOOL = 'record_workflow_transition_observation';
 const PROJECT_AGENT_SOURCE_TOOLS = new Set([
+  'call_employee_tool',
+  'begin_task_context',
+  'verify_task_checkpoint',
+  'checkpoint_task_knowledge',
+  'get_collaboration_preferences',
+  'capture_session_knowledge',
+  'record_decision_trace',
   'create_project_agent_assignment',
   'replace_project_agent_assignment',
   'coordinate_project_agent_task',
   'submit_project_agent_task',
   'get_project_agent_context',
+  'get_project_agent_memory',
+  'checkpoint_project_agent_memory',
   'record_project_agent_task_activity',
   'preflight_executor',
   'report_executor_health',
@@ -15,6 +24,7 @@ const PROJECT_AGENT_SOURCE_TOOLS = new Set([
 ]);
 
 const SESSION_ID_TOOLS = new Set([
+  'get_collaboration_preferences',
   'begin_task_context',
   'verify_task_checkpoint',
   'capture_session_knowledge',
@@ -51,14 +61,26 @@ export function normalizeAgentSessionInput(
     }
     const {
       sessionId: _sessionId,
+      session_id: _session_id,
       idempotencyKey: _idempotencyKey,
+      idempotency_key: _idempotency_key,
       observedAt: _observedAt,
+      observed_at: _observed_at,
       hostSessionId: _hostSessionId,
+      host_session_id: _host_session_id,
       hostObservedAt: _hostObservedAt,
+      host_observed_at: _host_observed_at,
+      sourceApplication: _sourceApplication,
+      source_application: _source_application,
+      sourceSessionId: _sourceSessionId,
+      source_session_id: _source_session_id,
+      sourceSessionVerified: _sourceSessionVerified,
+      source_session_verified: _source_session_verified,
       ...safeInput
     } = input ?? {};
     return {
       ...safeInput,
+      sourceApplication: normalizeMcpSourceApplication(sourceApplication),
       hostSessionId,
       hostObservedAt: clock().toISOString()
     };
@@ -73,24 +95,28 @@ export function normalizeAgentSessionInput(
       source_application: _source_application,
       sourceSessionId: _sourceSessionId,
       source_session_id: _source_session_id,
+      sourceSessionVerified: _sourceSessionVerified,
+      source_session_verified: _source_session_verified,
       ...safeInput
     } = input ?? {};
     return {
       ...safeInput,
+      ...(SESSION_ID_TOOLS.has(name) && nativeThreadId ? { sessionId: nativeThreadId } : {}),
       sourceApplication: safeSourceApplication,
-      sourceSessionId: hostSessionId
+      sourceSessionId: hostSessionId,
+      ...(name === 'call_employee_tool' ? { sourceSessionVerified: Boolean(nativeThreadId && nativeThreadId === hostSessionId) } : {}),
     };
   }
   if (!nativeThreadId || !SESSION_ID_TOOLS.has(name)) return input;
   if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
-  if (typeof input.sessionId !== 'string' || input.sessionId.trim() === nativeThreadId) {
+  if (typeof input.sessionId !== 'string' || input.sessionId === nativeThreadId) {
     return input;
   }
   return { ...input, sessionId: nativeThreadId };
 }
 
 export function normalizeMcpSourceApplication(value) {
-  if (!['codex', 'claude_code', 'cursor', 'kiro', 'other'].includes(value)) {
+  if (!['codex', 'claude', 'claude_code', 'cursor', 'kiro', 'other'].includes(value)) {
     throw new TypeError('Unsupported MCP source application');
   }
   return value;

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

@@ -18,59 +18,91 @@ export class TaskContextRegistry {
     this.tokens = new Map();
   }
 
-  begin({ sessionId, personalProjectId }) {
+  begin({ sessionId, turnId = null, personalProjectId, projectAgentId = null,
+    sourceApplication = 'other', sourceSessionId = null, memoryRevision = null }) {
     assertNonEmpty(sessionId, 'sessionId');
-    const previous = this.sessions.get(sessionId) ?? null;
+    const key = sessionKey(sourceApplication, sessionId);
+    const previous = this.sessions.get(key) ?? null;
+    if (!previous) this.#reserveSessionSlot();
     if (previous) this.tokens.delete(previous.token);
 
     const task = {
       token: this.tokenFactory(),
       sessionId,
+      turnId,
       personalProjectId: personalProjectId ?? null,
+      projectAgentId,
+      sourceApplication,
+      sourceSessionId,
+      memoryRevision,
+      agentMemory: null,
       checkpoint: null
     };
-    this.sessions.delete(sessionId);
-    this.sessions.set(sessionId, task);
+    this.sessions.delete(key);
+    this.sessions.set(key, task);
     this.tokens.set(task.token, task);
-    this.#evictOldest();
     return {
-      ...task,
-      previousCheckpointMissing: Boolean(previous && !previous.checkpoint)
+      ...snapshot(task),
+      previousCheckpointMissing: Boolean(previous && (!previous.checkpoint || previous.checkpoint.phase === 'prepare'))
     };
   }
 
-  checkpoint(token, checkpoint) {
-    assertNonEmpty(token, 'taskContextToken');
-    const task = this.tokens.get(token);
-    if (!task) throw unknownTokenError();
-    if (task.checkpoint) {
-      if (sameCheckpoint(task.checkpoint, checkpoint)) return task;
+  checkpoint(token, checkpoint, sourceApplication = 'other') {
+    const task = this.#task(token, sourceApplication);
+    if (task.checkpoint?.phase === 'prepare') {
+      if (!sameCheckpointClaim(task.checkpoint, checkpoint)) {
+        throw checkpointConflict('Task checkpoint has different input');
+      }
+    } else if (task.checkpoint) {
+      if (sameCheckpoint(task.checkpoint, checkpoint)) return snapshot(task);
+      throw checkpointConflict(
+        'Fuli task context has already been checkpointed with a different disposition'
+      );
+    }
+    task.checkpoint = Object.freeze({ ...checkpoint, phase: 'complete' });
+    return snapshot(task);
+  }
+
+  prepare(token, checkpoint, sourceApplication = 'other', agentMemory = null) {
+    const task = this.#task(token, sourceApplication);
+    if (agentMemory !== null && agentMemory !== undefined) {
       throw new ApplicationError(
         ApplicationErrorCode.VALIDATION,
-        'Fuli task context has already been checkpointed with a different disposition'
+        'The in-memory task context registry cannot atomically persist durable Agent memory'
       );
     }
-    task.checkpoint = Object.freeze({ ...checkpoint });
-    return task;
+    if (task.checkpoint && !sameCheckpointClaim(task.checkpoint, checkpoint)) {
+      throw checkpointConflict('Task checkpoint has different input');
+    }
+    if (!task.checkpoint) task.checkpoint = { ...checkpoint, phase: 'prepare' };
+    return snapshot(task);
   }
 
-  context(token) {
+  context(token, sourceApplication = 'other') {
+    return snapshot(this.#task(token, sourceApplication));
+  }
+
+  #task(token, sourceApplication) {
     assertNonEmpty(token, 'taskContextToken');
     const task = this.tokens.get(token);
-    if (!task) throw unknownTokenError();
+    if (!task || task.sourceApplication !== sourceApplication) throw unknownTokenError();
+    const key = sessionKey(task.sourceApplication, task.sessionId);
+    if (this.sessions.get(key) !== task) throw unknownTokenError();
+    this.sessions.delete(key);
+    this.sessions.set(key, task);
     return task;
   }
 
-  verify(sessionId) {
+  verify(sessionId, sourceApplication = 'other') {
     assertNonEmpty(sessionId, 'sessionId');
-    const task = this.sessions.get(sessionId);
+    const task = this.sessions.get(sessionKey(sourceApplication, sessionId));
     if (!task) {
       return {
         status: 'not_started',
         guidance: 'No Fuli task context was started; do not block the Agent.'
       };
     }
-    if (task.checkpoint) {
+    if (task.checkpoint && task.checkpoint.phase !== 'prepare') {
       return {
         status: 'checkpointed',
         disposition: task.checkpoint.disposition
@@ -79,27 +111,54 @@ export class TaskContextRegistry {
     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.'
+      task_context_token: task.token,
+      reason: `FULI_CHECKPOINT_REQUIRED: ${task.token} 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);
+  #reserveSessionSlot() {
+    if (this.sessions.size < MAX_ACTIVE_SESSIONS) return;
+    for (const [key, task] of this.sessions) {
+      if (task.checkpoint?.phase !== 'complete') continue;
+      this.sessions.delete(key);
       this.tokens.delete(task.token);
+      return;
     }
+    throw new ApplicationError(
+      ApplicationErrorCode.VALIDATION,
+      'Fuli has too many unfinished in-memory task contexts; finish an existing context or restart this fallback MCP process'
+    );
   }
 }
 
+function snapshot(task) {
+  return structuredClone(task);
+}
+
+function sessionKey(sourceApplication, sessionId) {
+  return JSON.stringify([sourceApplication, sessionId]);
+}
+
 function assertNonEmpty(value, label) {
   if (typeof value !== 'string' || !value.trim()) {
-    throw new TypeError(`${label} must be a nonempty string`);
+    throw new ApplicationError(
+      ApplicationErrorCode.VALIDATION,
+      `${label} must be a nonempty string`
+    );
   }
 }
 
 function sameCheckpoint(left, right) {
-  return left.disposition === right.disposition
-    && left.reason === right.reason
+  return sameCheckpointClaim(left, right)
     && left.captureStatus === right.captureStatus;
 }
+
+function sameCheckpointClaim(left, right) {
+  return left.fingerprint === right.fingerprint
+    && left.disposition === right.disposition
+    && left.reason === right.reason;
+}
+
+function checkpointConflict(message) {
+  return new ApplicationError(ApplicationErrorCode.VALIDATION, message);
+}

package/src/mcp/tool-annotations.js

@@ -1,4 +1,6 @@
 const READ_TOOLS = new Set([
+  'list_employee_templates',
+  'list_employee_tools',
   'verify_task_checkpoint',
   'search_current_project_knowledge',
   'discover_common_knowledge_candidates',
@@ -11,6 +13,7 @@ const READ_TOOLS = new Set([
   'get_project_agent',
   'list_project_agent_assignments',
   'get_project_agent_context',
+  'get_project_agent_memory',
   'view_project_agent_task',
   'view_project_agent_activity',
   'get_project_agent_coordination_policy',
@@ -33,8 +36,11 @@ const READ_TOOLS = new Set([
 ]);
 
 const WRITE_TOOLS = new Set([
+  'recruit_employee',
+  'call_employee_tool',
   'begin_task_context',
   'checkpoint_task_knowledge',
+  'checkpoint_project_agent_memory',
   'get_collaboration_preferences',
   'get_user_taste_skill',
   'resolve_deferred_preference_conflict',
@@ -93,6 +99,7 @@ const WRITE_TOOLS = new Set([
 ]);
 
 const DESTRUCTIVE_TOOLS = new Set([
+  'recruit_employee',
   'resolve_deferred_preference_conflict',
   'apply_common_knowledge_promotion',
   'review_project_proposal',
@@ -109,7 +116,7 @@ export function annotationsFor(name) {
   return {
     readOnlyHint: readOnly,
     destructiveHint: DESTRUCTIVE_TOOLS.has(name),
-    idempotentHint: readOnly || name === 'upsert_personal_project' ||
+    idempotentHint: readOnly || name === 'recruit_employee' || name === 'upsert_personal_project' ||
       name === 'upsert_project_agent' ||
       name === 'delete_project_agent' ||
       name === 'cleanup_test_project_agents' ||
@@ -131,7 +138,8 @@ export function annotationsFor(name) {
       name === 'record_knowledge_usage' || name === 'record_decision_trace' ||
       name === 'record_knowledge_feedback' ||
       name === 'record_workflow_transition_observation' ||
-      name === 'checkpoint_task_knowledge',
+      name === 'checkpoint_task_knowledge' ||
+      name === 'checkpoint_project_agent_memory',
     openWorldHint: name === 'capture_session_knowledge' ||
       name === 'coordinate_project_agent_task' ||
       name === 'submit_project_agent_task' ||

package/src/mcp/tool-result.js

@@ -100,9 +100,11 @@ export function applicationErrorMessage(error) {
   return boundedMessage(String(error.message));
 }
 
-export function protocolErrorResult(message) {
+export function protocolErrorResult(message, validationErrors = []) {
   if (message.includes('Input validation error')) {
-    return errorToolResult(new ApplicationError('validation', 'Invalid tool arguments'));
+    const error = new ApplicationError('validation', 'Invalid tool arguments');
+    error.validationErrors = validationErrors;
+    return errorToolResult(error);
   }
   return errorToolResult(new Error('Protocol tool failure'));
 }
@@ -117,8 +119,10 @@ function sanitize(value, state, seen = new WeakSet(), depth = 0) {
   seen.add(value);
   if (Array.isArray(value)) {
     if (value.length > RESULT_ITEM_LIMIT) state.truncated = true;
-    return value.slice(0, RESULT_ITEM_LIMIT)
+    const result = value.slice(0, RESULT_ITEM_LIMIT)
       .map((item) => sanitize(item, state, seen, depth + 1));
+    seen.delete(value);
+    return result;
   }
 
   const sanitized = {};
@@ -132,6 +136,7 @@ function sanitize(value, state, seen = new WeakSet(), depth = 0) {
     sanitized[key] = sanitize(item, state, seen, depth + 1);
     included += 1;
   }
+  seen.delete(value);
   return sanitized;
 }
 

package/src/mcp-server.js

@@ -11,6 +11,7 @@ import {
   resolveGraphRuntimeOptions
 } from './graphiti/runtime-config.js';
 import { runStdio } from './mcp/runtime.js';
+import { prepareDirectAgentToolCall } from './mcp/direct-call.js';
 import { normalizeMcpSourceApplication } from './mcp/session-id.js';
 import { applicationErrorMessage } from './mcp/tool-result.js';
 
@@ -30,13 +31,19 @@ async function main(args) {
   }
 
   const { runtimeConfigPath } = resolveGraphRuntimeOptions(args, process.env);
-  if (args.includes('--call')) {
-    await runCall({ args, runtimeConfigPath });
-    return;
-  }
   const configuredSourceApplication = args.includes('--source-application')
     ? requiredOption(args, '--source-application')
     : null;
+  if (args.includes('--call')) {
+    await runCall({
+      args,
+      runtimeConfigPath,
+      sourceApplication: configuredSourceApplication
+        ? normalizeMcpSourceApplication(configuredSourceApplication)
+        : 'other'
+    });
+    return;
+  }
   await runStdio({
     runtimeConfigPath,
     sourceApplication: configuredSourceApplication
@@ -45,15 +52,20 @@ async function main(args) {
   });
 }
 
-async function runCall({ args, runtimeConfigPath }) {
+async function runCall({ args, runtimeConfigPath, sourceApplication }) {
+  const toolName = requiredOption(args, '--call');
+  const prepared = await prepareDirectAgentToolCall({
+    toolName,
+    input: parseInput(args),
+    sourceApplication
+  });
   const app = openFederatedGraphApplication({ runtimeConfigPath });
   const leaseClient = createRuntimeLeaseClient({ runtimeConfigPath });
   bindRuntimeLeaseAgentTools(app, leaseClient);
   try {
-    const toolName = requiredOption(args, '--call');
     const result = await leaseClient.withGraphLease(
       `cli-call:${toolName}`,
-      () => callAgentTool(app, toolName, parseInput(args))
+      () => callAgentTool(app, toolName, prepared.input)
     );
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   } finally {
@@ -86,7 +98,7 @@ function startupMessage(error) {
 
 function helpText() {
   return 'Usage: node src/mcp-server.js [--runtime-config <graph-runtime.json>] ' +
-    '[--source-application <codex|claude_code|cursor|kiro|other>]\n' +
+    '[--source-application <codex|claude|claude_code|cursor|kiro|other>]\n' +
     '       node src/mcp-server.js --tools\n' +
     '       node src/mcp-server.js --runtime-config <graph-runtime.json> ' +
     '--call <tool> [--input <json>]\n';

package/src/native-runtime/runtime.js

@@ -13,6 +13,7 @@ import {
 } from 'node:fs';
 import {
   mkdir,
+  readdir,
   readFile,
   rename,
   rm,
@@ -22,7 +23,7 @@ import {
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createConnection } from 'node:net';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 
 import { FULI_VERSION } from '../package-metadata.js';
 import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
@@ -284,12 +285,18 @@ export async function ensureNativeRuntime(input, dependencies = {}) {
   }
 
   const providerPython = join(input.paths.nativeProviderVenvPath, 'bin', 'python');
+  const providerSource = join(dirname(input.paths.graphComposePath), 'graph-provider');
+  const providerFingerprint = await deps.providerSourceFingerprint(providerSource);
+  if (!/^[a-f0-9]{64}$/.test(providerFingerprint)) {
+    throw new Error('Native Graph Provider source fingerprint is invalid.');
+  }
   const expected = {
     version: MANIFEST_VERSION,
     status: 'ready',
     mode: 'native',
     neo4jVersion: NATIVE_NEO4J_VERSION,
     providerVersion: `${FULI_VERSION}+native.${PROVIDER_RUNTIME_REVISION}`,
+    providerFingerprint,
     javaHome,
     uvCommand,
     neo4jHome: input.paths.nativeNeo4jHome,
@@ -307,14 +314,17 @@ export async function ensureNativeRuntime(input, dependencies = {}) {
       sha256: NATIVE_NEO4J_SHA256
     });
   }
-  if (!deps.pathExists(providerPython) || saved?.providerVersion !== expected.providerVersion) {
+  if (
+    !deps.pathExists(providerPython) ||
+    saved?.providerVersion !== expected.providerVersion ||
+    saved?.providerFingerprint !== expected.providerFingerprint
+  ) {
     deps.onProgress(input, 'Installing the native Graph Provider…');
     await deps.installProvider({
       uvCommand,
       venvPath: input.paths.nativeProviderVenvPath,
       providerPython,
-      providerSource: join(dirname(dirname(input.paths.graphComposePath)), 'graph-provider'),
-      packageRoot: dirname(input.paths.graphComposePath)
+      providerSource
     });
   }
   if (!neo4jReady(input.paths, deps.pathExists) || !deps.pathExists(providerPython)) {
@@ -356,6 +366,7 @@ function manifestReady(saved, expected, paths, pathExists) {
     saved.mode === expected.mode &&
     saved.neo4jVersion === expected.neo4jVersion &&
     saved.providerVersion === expected.providerVersion &&
+    saved.providerFingerprint === expected.providerFingerprint &&
     saved.javaHome === expected.javaHome &&
     saved.uvCommand === expected.uvCommand &&
     saved.neo4jHome === expected.neo4jHome &&
@@ -385,6 +396,7 @@ function nativeDependencies(overrides) {
     resolveUvCommand,
     installNeo4j,
     installProvider,
+    providerSourceFingerprint,
     onProgress: (input, message) => input.onProgress?.(message),
     ...overrides
   };
@@ -431,15 +443,53 @@ async function installNeo4j({ paths, home, url, sha256 }) {
   await runCommand('tar', ['-xzf', archive, '-C', paths.nativeRuntimeDir]);
 }
 
-async function installProvider({ uvCommand, venvPath, providerPython, packageRoot }) {
+async function installProvider({ uvCommand, venvPath, providerPython, providerSource }) {
   await mkdir(dirname(venvPath), { recursive: true });
   if (!existsSync(providerPython)) {
     await runCommand(uvCommand, ['venv', '--python', '3.12', '--seed', venvPath]);
   }
-  await runCommand(uvCommand, [
+  await runCommand(uvCommand, nativeProviderInstallArguments({
+    providerPython,
+    providerSource
+  }));
+}
+
+export function nativeProviderInstallArguments({ providerPython, providerSource }) {
+  return [
     'pip', 'install', '--python', providerPython, '--upgrade',
-    join(packageRoot, 'graph-provider')
-  ]);
+    '--reinstall-package', 'fuli-graph-provider',
+    providerSource
+  ];
+}
+
+async function providerSourceFingerprint(providerSource) {
+  const files = [
+    join(providerSource, 'pyproject.toml'),
+    ...await pythonSourceFiles(join(providerSource, 'fuli_graph'))
+  ].sort();
+  const hash = createHash('sha256');
+  for (const path of files) {
+    const name = relative(providerSource, path).replaceAll('\\', '/');
+    hash.update(name);
+    hash.update('\0');
+    hash.update(await readFile(path));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+async function pythonSourceFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== '__pycache__') files.push(...await pythonSourceFiles(path));
+    } else if (entry.isFile() && entry.name.endsWith('.py')) {
+      files.push(path);
+    }
+  }
+  return files;
 }
 
 async function downloadFile(url, destination) {