fuli-context 0.7.3 → 0.7.4-beta.1

package/src/graphiti/federated-search-support.js

@@ -0,0 +1,102 @@
+import { canonicalProviderUrl } from './runtime-config.js';
+import {
+  relatedProjectSuggestionsForSearchResults
+} from './related-project-suggestions.js';
+
+export function retrievalGuidanceForScope(personalProjectScope) {
+  if (personalProjectScope === 'all_local_confirmed') {
+    return {
+      currentPersonalProjectScope: 'all_local_confirmed',
+      markerToUseIfNoSupportingEvidence: 'noMatchSourceMarker',
+      requiredNextActionIfNoSupportingEvidence:
+        'search_current_workspace_files_or_ask_for_safe_root',
+      workspaceFileSearch: {
+        available: true,
+        consentSource: 'bounded_expansion_confirmation',
+        rootBoundary: 'current_working_directory',
+        requiresSafeProjectOrWorkspaceRoot: true,
+        forbiddenBroadRoots: ['user_home', 'filesystem_root'],
+        readOnly: true,
+        includesPublicProjects: false
+      },
+      instruction: 'Use read-only local file search in the current repository or explicit ' +
+        'workspace root, preserving exact names first. If the working directory is the user ' +
+        'home, filesystem root, or otherwise too broad, ask for a safe root. Never search ' +
+        'outside that root or inspect credential stores; if no evidence supports the answer, ' +
+        'ask for a source clue.'
+    };
+  }
+  return {
+    currentPersonalProjectScope: 'bounded',
+    markerToUseIfNoSupportingEvidence: 'noMatchSourceMarker',
+    requiredNextActionIfNoSupportingEvidence:
+      'ask_user_to_confirm_all_local_and_workspace_search',
+    expansion: {
+      available: true,
+      requiresExplicitUserConfirmation: true,
+      input: { personalProjectScope: 'all_local_confirmed' },
+      readOnly: true,
+      oneQueryOnly: true,
+      includesPublicProjects: false,
+      includesCurrentWorkspaceFiles: true
+    },
+    instruction: 'Ask whether to widen this one read-only lookup to all registered local ' +
+      'personal projects and, if still unresolved, current repository or workspace files. ' +
+      'Exclude public projects and paths outside the current workspace; then stop and wait.'
+  };
+}
+
+export async function loadSearchRelatedProjectSuggestions(application, result) {
+  const hasExactProjectResult = [
+    ...(result?.facts ?? []),
+    ...(result?.entities ?? [])
+  ].some((item) => (
+    typeof item?.defined_project_id === 'string' &&
+    item.defined_project_id &&
+    !item.inherited_from_project_id &&
+    Number(item.scope_distance ?? 0) === 0
+  ));
+  if (!hasExactProjectResult) {
+    return { status: 'not_applicable', suggestions: [] };
+  }
+  try {
+    const graph = await application.personal.graph(
+      application.config.personal.spaceId,
+      2000
+    );
+    return {
+      status: graph?.truncated ? 'partial' : 'available',
+      suggestions: relatedProjectSuggestionsForSearchResults(graph, result)
+    };
+  } catch {
+    return { status: 'unavailable', suggestions: [] };
+  }
+}
+
+export function groupSubscriptions(subscriptions) {
+  const grouped = new Map();
+  for (const subscription of subscriptions) {
+    const url = canonicalProviderUrl(subscription.provider_url);
+    if (!grouped.has(url)) grouped.set(url, []);
+    grouped.get(url).push(subscription);
+  }
+  return grouped;
+}
+
+export function rankedSearchItems(searchResults, key, limit) {
+  return searchResults
+    .flatMap((result) => result[key])
+    .map((item, index) => ({ item, index }))
+    .sort((left, right) =>
+      searchItemScore(right.item) - searchItemScore(left.item) ||
+      left.index - right.index
+    )
+    .slice(0, limit)
+    .map(({ item }) => item);
+}
+
+function searchItemScore(item) {
+  return typeof item?.score === 'number' && Number.isFinite(item.score)
+    ? item.score
+    : 0;
+}

package/src/graphiti/knowledge-provider-mapping.js

@@ -1,6 +1,9 @@
+import { ApplicationError } from '../app/application-error.js';
 import { onlineSourceUri } from './source-uri.js';
 
 export function providerEpisode(input) {
+  assertReasoningSummaries(input.entities, 'entities');
+  assertReasoningSummaries(input.relationships, 'relationships');
   return {
     idempotency_key: input.idempotencyKey,
     session_id: input.sessionId,
@@ -55,6 +58,18 @@ export function providerEpisode(input) {
   };
 }
 
+function assertReasoningSummaries(items, collectionName) {
+  items.forEach((item, index) => {
+    const originQuadrant = item.originQuadrant ?? 'known_known';
+    if (originQuadrant === 'known_known' || item.reasoningSummary?.trim()) return;
+    throw new ApplicationError(
+      'validation',
+      `${collectionName}[${index}].reasoningSummary is required when ` +
+      `originQuadrant is ${originQuadrant}`
+    );
+  });
+}
+
 export function assertPublicKnowledgeEligible(episode) {
   const blocked = [...episode.entities, ...episode.relationships].find((item) =>
     item.profile_aspect ||

package/src/graphiti/provider-client.js

@@ -2,26 +2,48 @@ import { ApplicationError } from '../app/application-error.js';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const MAX_REQUEST_TIMEOUT_MS = 2_147_483_647;
+const MAX_PROVIDER_VALIDATION_ERRORS = 5;
 
 export class ProviderRequestError extends ApplicationError {
-  constructor(message, { status = 0, code = 'provider_error', details = null } = {}) {
+  constructor(message, {
+    status = 0,
+    code = 'provider_error',
+    details = null,
+    diagnostic = null,
+    validationErrors = []
+  } = {}) {
     super(code, message);
     this.name = 'ProviderRequestError';
     this.status = status;
     this.code = code;
     this.details = details;
+    this.diagnostic = diagnostic;
+    this.validationErrors = Array.isArray(validationErrors)
+      ? validationErrors.slice(0, MAX_PROVIDER_VALIDATION_ERRORS)
+      : [];
   }
 }
 
 export class GraphitiProviderClient {
+  #workflowObservationToken;
+
   constructor({
     baseUrl,
     accessToken,
+    workflowObservationToken = null,
     fetchImpl = globalThis.fetch,
     requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
   }) {
     if (!baseUrl) throw new TypeError('Graphiti provider baseUrl is required');
     if (!accessToken) throw new TypeError('Graphiti provider accessToken is required');
+    if (workflowObservationToken !== null && (
+      typeof workflowObservationToken !== 'string' ||
+      workflowObservationToken.trim().length < 32
+    )) {
+      throw new TypeError(
+        'MCP host workflow observation credential must contain at least 32 characters'
+      );
+    }
     if (typeof fetchImpl !== 'function') throw new TypeError('fetch implementation is required');
     if (!Number.isSafeInteger(requestTimeoutMs) ||
         requestTimeoutMs < 1 ||
@@ -30,6 +52,7 @@ export class GraphitiProviderClient {
     }
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.accessToken = accessToken;
+    this.#workflowObservationToken = workflowObservationToken?.trim() ?? null;
     this.fetch = fetchImpl;
     this.requestTimeoutMs = requestTimeoutMs;
   }
@@ -118,6 +141,14 @@ export class GraphitiProviderClient {
   commit(input) {
     return this.#request('/v1/knowledge/commits', { method: 'POST', body: input });
   }
+  recordWorkflowObservation(input) {
+    if (!this.#workflowObservationToken) {
+      throw new TypeError('MCP host workflow observation credential is not configured');
+    }
+    return this.#request('/v1/workflow-observations', {
+      method: 'POST', body: input, workflowObservation: true
+    });
+  }
   startKnowledgeReview(input) {
     return this.#request('/v1/knowledge/reviews/start', {
       method: 'POST', body: input
@@ -138,6 +169,16 @@ export class GraphitiProviderClient {
       method: 'POST', body: input
     });
   }
+  searchWorkflowCandidates(input) {
+    return this.#request('/v1/workflow-candidates/search', {
+      method: 'POST', body: input
+    });
+  }
+  recommendWorkflowCandidates(input) {
+    return this.#request('/v1/workflow-candidates/recommendations', {
+      method: 'POST', body: input
+    });
+  }
   reviseKnowledgeItem(itemId, input) {
     return this.#request(`/v1/knowledge/items/${encodeURIComponent(itemId)}`, {
       method: 'PATCH', body: input
@@ -196,6 +237,33 @@ export class GraphitiProviderClient {
       method: 'POST', body: input
     });
   }
+  personalGlobalPreferenceDecisionStatus(input) {
+    return this.#request(
+      '/v1/personal-global-preference-candidates/decision-status',
+      { method: 'POST', body: input }
+    );
+  }
+  personalGlobalPreferenceScopeOptions(candidateId, input) {
+    return this.#request(
+      '/v1/personal-global-preference-candidates/' +
+      `${encodeURIComponent(candidateId)}/scope-options`,
+      { method: 'POST', body: input }
+    );
+  }
+  inspectPersonalGlobalPreferenceDecision(candidateId, input) {
+    return this.#request(
+      '/v1/personal-global-preference-candidates/' +
+      `${encodeURIComponent(candidateId)}/decision-inspection`,
+      { method: 'POST', body: input }
+    );
+  }
+  applyPersonalGlobalPreferenceDecision(candidateId, input) {
+    return this.#request(
+      '/v1/personal-global-preference-candidates/' +
+      `${encodeURIComponent(candidateId)}/decision`,
+      { method: 'POST', body: input }
+    );
+  }
   deferPreferenceConflict(input) {
     return this.#request('/v1/preference-conflicts/defer', {
       method: 'POST', body: input
@@ -270,10 +338,14 @@ export class GraphitiProviderClient {
   async #request(path, {
     method = 'GET',
     body,
-    authenticated = true
+    authenticated = true,
+    workflowObservation = false
   } = {}) {
     const headers = { accept: 'application/json' };
     if (authenticated) headers.authorization = `Bearer ${this.accessToken}`;
+    if (workflowObservation) {
+      headers['x-fuli-workflow-observation-token'] = this.#workflowObservationToken;
+    }
     if (body !== undefined) headers['content-type'] = 'application/json';
     const controller = new AbortController();
     let timedOut = false;
@@ -293,23 +365,36 @@ export class GraphitiProviderClient {
       });
       payload = await parseResponse(response);
     } catch (error) {
+      const diagnostic = {
+        category: timedOut ? 'provider_timeout' : 'provider_unavailable',
+        status: timedOut ? 504 : 0,
+        detail: timedOut
+          ? 'Graphiti provider request timed out.'
+          : 'Graphiti provider is unavailable.'
+      };
       throw new ProviderRequestError(
-        timedOut
-          ? 'Graphiti provider request timed out'
-          : 'Graphiti provider is unavailable',
+        diagnostic.detail,
         {
-          status: timedOut ? 504 : 0,
-          code: timedOut ? 'provider_timeout' : 'provider_unavailable',
-          details: timedOut ? null : error instanceof Error ? error.message : null
+          status: diagnostic.status,
+          code: diagnostic.category,
+          details: timedOut ? null : diagnostic,
+          diagnostic
         }
       );
     } finally {
       clearTimeout(timeout);
     }
     if (!response.ok) {
+      const diagnostic = providerErrorDiagnostic(response.status, payload);
       throw new ProviderRequestError(
-        typeof payload?.detail === 'string' ? payload.detail : 'Graphiti provider request failed',
-        { status: response.status, details: payload }
+        diagnostic.detail,
+        {
+          status: response.status,
+          code: diagnostic.category,
+          details: diagnostic,
+          diagnostic,
+          validationErrors: diagnostic.validationErrors
+        }
       );
     }
     return payload;
@@ -322,3 +407,70 @@ async function parseResponse(response) {
   const text = await response.text();
   return text ? { detail: text } : null;
 }
+
+function providerErrorDiagnostic(status, payload) {
+  const category = status >= 500 && status <= 599
+    ? 'provider_http_5xx'
+    : 'provider_error';
+  if (category === 'provider_http_5xx') {
+    return {
+      category,
+      status,
+      detail: `Graphiti provider returned HTTP ${status}.`
+    };
+  }
+  const validationErrors = providerValidationErrors(payload);
+  return {
+    category,
+    status,
+    detail: sanitizeProviderDetail(providerErrorMessage(payload, validationErrors)),
+    validationErrors
+  };
+}
+
+function providerErrorMessage(payload, validationErrors = providerValidationErrors(payload)) {
+  if (typeof payload?.detail === 'string') return payload.detail;
+  if (!validationErrors.length) return 'Graphiti provider request failed';
+  const messages = validationErrors.map(({ field, message }) => (
+    field ? `${field} — ${message}` : message
+  ));
+  return `Graphiti provider rejected the request — ${messages.join('; ')}`;
+}
+
+function sanitizeProviderDetail(value) {
+  return String(value ?? 'Graphiti provider request failed')
+    .replace(/Bearer\s+\S+/gi, 'Bearer <redacted>')
+    .replace(/(?:token|secret|password|api[_-]?key)\s*[:=]\s*\S+/gi, '$1=<redacted>')
+    .replace(/(?:\/Users\/|\/home\/|\/private\/|\/tmp\/)[^\s"']+/g, '<path>')
+    .replace(/https?:\/\/[^\s"']+/gi, '<url>')
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replaceAll(':', ' —')
+    .slice(0, 320) || 'Graphiti provider request failed';
+}
+
+// Issue source: WZ.
+// Provider validation failures must expose the field and actionable reason
+// without echoing FastAPI's submitted input payload.
+function providerValidationErrors(payload) {
+  if (!Array.isArray(payload?.detail)) return [];
+  return payload.detail
+    .filter((item) => item && typeof item.msg === 'string' && item.msg.trim())
+    .slice(0, MAX_PROVIDER_VALIDATION_ERRORS)
+    .map((item) => ({
+      field: validationLocation(item.loc),
+      message: sanitizeProviderDetail(item.msg.trim())
+    }));
+}
+
+function validationLocation(loc) {
+  if (!Array.isArray(loc)) return '';
+  return loc
+    .filter((segment) => segment !== 'body')
+    .reduce((path, segment) => {
+      if (typeof segment === 'number') return `${path}[${segment}]`;
+      if (typeof segment !== 'string' || !segment) return path;
+      return path ? `${path}.${segment}` : segment;
+    }, '');
+}

package/src/graphiti/related-project-suggestions.js

@@ -0,0 +1,109 @@
+const SUGGESTED_RELATION_TYPES = new Set(['RELATED_TO']);
+
+export function relatedProjectSuggestions(graph, currentProjectId) {
+  const nodes = new Map(
+    (graph?.nodes ?? [])
+      .filter((node) => projectId(node))
+      .map((node) => [node.id, node])
+  );
+  const currentNodes = new Set(
+    [...nodes.values()]
+      .filter((node) => projectId(node) === currentProjectId)
+      .map(({ id }) => id)
+  );
+  const suggestions = [];
+
+  for (const edge of graph?.edges ?? []) {
+    if (!SUGGESTED_RELATION_TYPES.has(edge.type)) continue;
+    if (relationStatus(edge) !== 'active') continue;
+    if (relationAuthority(edge) !== 'human_review') continue;
+    const currentIsSource = currentNodes.has(edge.source);
+    const currentIsTarget = currentNodes.has(edge.target);
+    if (currentIsSource === currentIsTarget) continue;
+    const relatedNode = nodes.get(currentIsSource ? edge.target : edge.source);
+    const relatedProjectId = projectId(relatedNode);
+    if (!relatedProjectId || relatedProjectId === currentProjectId) continue;
+    suggestions.push({
+      personal_project_id: relatedProjectId,
+      project_name: relatedNode.name ?? relatedProjectId,
+      relation_id: edge.id,
+      relation_type: edge.type,
+      relation_status: 'active',
+      direction: currentIsSource ? 'outgoing' : 'incoming',
+      reason: edge.fact ?? `The current project has a ${edge.type} relation to ${relatedProjectId}.`,
+      requires_human_confirmation: true,
+      expansion_mode: 'one_time_read_only',
+      confirmed_search: {
+        tool: 'search_knowledge_graph',
+        personal_project_scope: 'bounded',
+        context_personal_project_ids: [relatedProjectId]
+      }
+    });
+  }
+
+  return suggestions.sort((left, right) => (
+    left.personal_project_id.localeCompare(right.personal_project_id)
+    || left.relation_id.localeCompare(right.relation_id)
+  ));
+}
+
+export function relatedProjectSuggestionsForSearchResults(graph, result) {
+  const resultIdsByProject = new Map();
+  for (const item of [...(result?.facts ?? []), ...(result?.entities ?? [])]) {
+    const projectId = exactProjectId(item);
+    if (!projectId) continue;
+    const resultIds = resultIdsByProject.get(projectId) ?? [];
+    if (typeof item.id === 'string' && item.id && !resultIds.includes(item.id)) {
+      resultIds.push(item.id);
+    }
+    resultIdsByProject.set(projectId, resultIds);
+  }
+
+  const suggestions = [];
+  for (const [projectId, resultIds] of resultIdsByProject) {
+    for (const suggestion of relatedProjectSuggestions(graph, projectId)) {
+      suggestions.push({
+        ...suggestion,
+        triggered_by_project_id: projectId,
+        triggered_by_result_ids: resultIds
+      });
+    }
+  }
+  return suggestions.sort((left, right) => (
+    left.triggered_by_project_id.localeCompare(right.triggered_by_project_id)
+    || left.personal_project_id.localeCompare(right.personal_project_id)
+    || left.relation_id.localeCompare(right.relation_id)
+  ));
+}
+
+export function relatedProjectGuidance(suggestions) {
+  if (suggestions.length === 0) return null;
+  const projectIds = suggestions
+    .map(({ personal_project_id: projectId }) => projectId)
+    .join(', ');
+  return 'Ask whether this task may add a one-time read-only search of exactly: ' +
+    `${projectIds}. Do not expand before explicit human confirmation.`;
+}
+
+function projectId(node) {
+  return node?.attributes?.projectId;
+}
+
+function relationStatus(edge) {
+  return edge?.attributes?.status ?? edge?.status ?? null;
+}
+
+function relationAuthority(edge) {
+  return edge?.attributes?.confirmationAuthority
+    ?? edge?.attributes?.confirmation_authority
+    ?? edge?.confirmation_authority
+    ?? null;
+}
+
+function exactProjectId(item) {
+  if (item?.inherited_from_project_id) return null;
+  if (Number(item?.scope_distance ?? 0) !== 0) return null;
+  return typeof item?.defined_project_id === 'string' && item.defined_project_id
+    ? item.defined_project_id
+    : null;
+}

package/src/graphiti/runtime-config.js

@@ -30,6 +30,11 @@ export function readGraphRuntimeConfig(path) {
 function validateConfig(config) {
   if (config?.version !== 1) fail('unsupported graph runtime config version');
   provider(config.personal, 'personal');
+  optionalSecret(
+    config.personal,
+    'workflowObservationToken',
+    'personal.workflowObservationToken'
+  );
   if (!config.personal.spaceId) fail('personal.spaceId is required');
   if (!Array.isArray(config.workspaces)) fail('workspaces must be an array');
   for (const [index, workspace] of config.workspaces.entries()) {
@@ -45,6 +50,15 @@ function provider(value, label) {
   value.providerUrl = canonicalProviderUrl(value.providerUrl);
 }
 
+function optionalSecret(value, property, label) {
+  if (value[property] === undefined) return;
+  const normalized = nonEmpty(value[property]);
+  if (!normalized || normalized.length < 32) {
+    fail(`${label} must contain at least 32 characters`);
+  }
+  value[property] = normalized;
+}
+
 export function canonicalProviderUrl(value) {
   const normalized = String(value).replace(/\/$/, '');
   let url;

package/src/graphiti/source-marker.js

@@ -156,9 +156,9 @@ function sourceMarkerMarkdown({ consoleUrl, citations }) {
 
 function knowledgeUrl(consoleUrl, { scope, spaceId, itemKind, itemId }) {
   const origin = safeLoopbackOrigin(consoleUrl) ?? DEFAULT_CONSOLE_URL;
-  const segments = ['knowledge', scope, spaceId, itemKind, itemId]
+  const segments = ['knowledge', scope, spaceId, 'directory', itemKind, itemId]
     .map((segment) => encodeURIComponent(segment));
-  return `${origin}/#/${segments.join('/')}`;
+  return `${origin}/${segments.join('/')}`;
 }
 
 function safeLoopbackOrigin(value) {