fuli-context 0.4.0 → 0.7.2

package/src/graphiti/task-knowledge-recall.js

@@ -0,0 +1,250 @@
+import { createFuliSourceMarker } from './source-marker.js';
+import { knowledgeItemRole } from './knowledge-item-role.js';
+import { detectSensitiveContent } from '../security/sensitive-content.js';
+
+const MAX_QUERIES = 4;
+const MAX_ITEMS_PER_KIND = 3;
+const MAX_ITEM_TEXT = 1000;
+
+const RECALL_INTENTS = Object.freeze([
+  {
+    category: 'release_delivery',
+    pattern: /(?:发布|发版|上线|部署|推送|再推|release|publish|push|deploy|ship|rollout|commit|github|\bgit\b)/iu,
+    queries: [
+      '发布 发版 版本 release publish runbook',
+      '推送 提交 push commit GitHub Connector runbook'
+    ]
+  },
+  {
+    category: 'access_authentication',
+    pattern: /(?:认证|登录|凭据|身份|令牌|密钥|credential|authentication|authorization|login|token|ssh)/iu,
+    queries: ['认证 登录 凭据 身份 credential authentication SSH token runbook']
+  },
+  {
+    category: 'artifact_location',
+    pattern: /(?:网址|地址|路由|端点|在哪里|在哪儿|哪里|(?:文档|文件).{0,12}(?:位置|路径|在哪)|(?:找|查).{0,12}(?:文档|文件)|\burl\b|route|endpoint|document location|file path|where)/iu,
+    queries: ['地址 URL 路由 route endpoint 部署 deployment 文档 document']
+  },
+  {
+    category: 'requirements_architecture_decision',
+    pattern: /(?:需求|约束|架构|设计决定|决策|原因|取舍|requirement|constraint|architecture|decision|rationale|tradeoff)/iu,
+    queries: ['需求 约束 架构 决策 原因 requirement constraint architecture decision rationale']
+  },
+  {
+    category: 'runbook_method',
+    pattern: /(?:方法|方式|流程|步骤|怎么做|如何做|runbook|workflow|procedure|how to)/iu,
+    queries: ['方法 方式 流程 步骤 runbook workflow procedure']
+  },
+  {
+    category: 'prior_context',
+    pattern: /(?:之前|以前|上次|已经存|保存过|记得|照旧|同样|还是用|不用再|先前|previous|earlier|remember|same as|again)/iu,
+    queries: ['先前 方法 规则 决策 runbook previous method decision']
+  }
+]);
+
+export const TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE = Object.freeze({
+  before_reasking:
+    'Before asking the user to repeat a stable project fact or method, inspect task_knowledge_recall and search Fuli when needed.',
+  focused_queries:
+    'Use one to four focused action, artifact, target-system, or identifier queries; never use the full conversational request as the only query.',
+  scope:
+    'Search only the exact active personal project, its explicitly inheritable knowledge, and the bounded personal-global profile.'
+});
+
+export function planTaskKnowledgeRecall(taskPrompt) {
+  if (typeof taskPrompt !== 'string' || !taskPrompt.trim()) {
+    return { status: 'not_requested', trigger_categories: [], queries: [] };
+  }
+  const prompt = singleLine(taskPrompt).slice(0, 8192);
+  if (detectSensitiveContent(prompt).restricted) {
+    return {
+      status: 'suppressed_sensitive',
+      trigger_categories: [],
+      queries: []
+    };
+  }
+  const matched = RECALL_INTENTS.filter(({ pattern }) => pattern.test(prompt));
+  if (!matched.length) {
+    return { status: 'not_needed', trigger_categories: [], queries: [] };
+  }
+  const queries = unique(matched.flatMap(({ queries: values }) => values));
+  const distinctive = distinctivePromptQuery(prompt);
+  if (distinctive) queries.push(distinctive);
+  return {
+    status: 'planned',
+    trigger_categories: matched.map(({ category }) => category),
+    queries: unique(queries).slice(0, MAX_QUERIES)
+  };
+}
+
+export async function recallTaskKnowledge(application, resolution, taskPrompt) {
+  const plan = planTaskKnowledgeRecall(taskPrompt);
+  if (plan.status !== 'planned') return recallWithoutSearch(plan.status, plan);
+  if (!resolution.personalProjectId) {
+    return {
+      status: 'project_unresolved',
+      trigger_categories: plan.trigger_categories,
+      query_count: plan.queries.length,
+      guidance: TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE,
+      facts: [],
+      entities: []
+    };
+  }
+
+  const settlements = await Promise.allSettled(plan.queries.map((query) =>
+    application.searchKnowledge({
+      personalSpaceId: application.config.personal.spaceId,
+      personalProjectId: resolution.personalProjectId,
+      query,
+      limit: 6,
+      includeHistorical: false,
+      includePending: false,
+      agentInvocation: true,
+      agentToolName: 'automatic_task_knowledge_recall'
+    })
+  ));
+  const results = settlements
+    .filter(({ status }) => status === 'fulfilled')
+    .map(({ value }) => value);
+  const failedQueryCount = settlements.length - results.length;
+  const facts = rankedUnique(
+    results.flatMap(({ facts = [] }) => facts),
+    'relationship'
+  ).slice(0, MAX_ITEMS_PER_KIND).map(compactFact);
+  const entities = rankedUnique(
+    results.flatMap(({ entities = [] }) => entities),
+    'entity'
+  ).slice(0, MAX_ITEMS_PER_KIND).map(compactEntity);
+  const sourceMarker = createFuliSourceMarker({
+    consoleUrl: application.consoleUrl,
+    facts,
+    entities,
+    projectScopePriority: 'strict'
+  });
+  const searched = results.length > 0;
+  return {
+    status: facts.length || entities.length
+      ? 'matched'
+      : failedQueryCount === settlements.length ? 'unavailable' : 'no_match',
+    partial: failedQueryCount > 0,
+    failed_query_count: failedQueryCount,
+    trigger_categories: plan.trigger_categories,
+    query_count: plan.queries.length,
+    guidance: TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE,
+    ...(searched ? {
+      sourceMarker,
+      noMatchSourceMarker: createFuliSourceMarker({
+        consoleUrl: application.consoleUrl
+      })
+    } : {}),
+    facts,
+    entities
+  };
+}
+
+function recallWithoutSearch(status, plan) {
+  return {
+    status,
+    trigger_categories: plan.trigger_categories,
+    query_count: plan.queries.length,
+    guidance: TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE,
+    facts: [],
+    entities: []
+  };
+}
+
+function rankedUnique(items, itemKind) {
+  const selected = new Map();
+  for (const item of items) {
+    const key = `${itemKind}:${item.id}`;
+    const current = selected.get(key);
+    if (!current || compareRecallItems(item, current) < 0) selected.set(key, item);
+  }
+  return [...selected.values()].sort(compareRecallItems);
+}
+
+function compareRecallItems(left, right) {
+  const leftLocal = left.defined_project_id ? 1 : 0;
+  const rightLocal = right.defined_project_id ? 1 : 0;
+  if (leftLocal !== rightLocal) return rightLocal - leftLocal;
+  const leftDistance = Number(left.scope_distance ?? 0);
+  const rightDistance = Number(right.scope_distance ?? 0);
+  if (leftDistance !== rightDistance) return leftDistance - rightDistance;
+  const leftSupporting = knowledgeItemRole(left) === 'supporting' ? 1 : 0;
+  const rightSupporting = knowledgeItemRole(right) === 'supporting' ? 1 : 0;
+  if (leftSupporting !== rightSupporting) return leftSupporting - rightSupporting;
+  return Number(right.score ?? 0) - Number(left.score ?? 0);
+}
+
+function compactFact(fact) {
+  return compactItem(fact, {
+    source_entity: fact.source_entity,
+    target_entity: fact.target_entity,
+    relationship: fact.relationship,
+    fact: boundedText(fact.fact)
+  });
+}
+
+function compactEntity(entity) {
+  return compactItem(entity, {
+    name: entity.name,
+    type: entity.type,
+    summary: boundedText(entity.summary)
+  });
+}
+
+function compactItem(item, content) {
+  return {
+    id: item.id,
+    space_id: item.space_id ?? item.spaceId,
+    scope: item.scope,
+    key: item.key ?? null,
+    defined_project_id: item.defined_project_id ?? null,
+    inherited_from_project_id: item.inherited_from_project_id ?? null,
+    scope_distance: item.scope_distance ?? 0,
+    confirmation_status: item.confirmation_status ?? null,
+    source_uris: item.source_uris ?? [],
+    score: item.score ?? null,
+    ...content
+  };
+}
+
+function distinctivePromptQuery(prompt) {
+  const quoted = [...prompt.matchAll(/[“”"']([^“”"']{2,80})[“”"']/gu)]
+    .map((match) => match[1]);
+  const versions = prompt.match(
+    /\bv?\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?\b/gu
+  ) ?? [];
+  const identifiers = prompt.match(
+    /\b[A-Za-z][A-Za-z0-9]{0,63}[_./-][A-Za-z0-9_.\/-]{1,127}\b/gu
+  ) ?? [];
+  const urls = [...prompt.matchAll(/https?:\/\/[^\s<>()]+/gu)]
+    .map((match) => safeUrlSearchTerm(match[0]))
+    .filter(Boolean);
+  return unique([...quoted, ...versions, ...identifiers, ...urls])
+    .slice(0, 4)
+    .join(' ')
+    .slice(0, 180);
+}
+
+function safeUrlSearchTerm(value) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return null;
+    return `${url.hostname}${url.pathname}`.slice(0, 120);
+  } catch {
+    return null;
+  }
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function singleLine(value) {
+  return String(value).replace(/[\r\n\t]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+}
+
+function boundedText(value) {
+  return singleLine(value ?? '').slice(0, MAX_ITEM_TEXT);
+}

package/src/http/api-router.js

@@ -1,8 +1,15 @@
 import { readJson, sendJson } from './response.js';
-import { handleLensRequest } from './lens-route.js';
+import { handleExternalKnowledgeApiRequest } from './external-knowledge-api-router.js';
 import { handleGraphApiRequest } from './graph-api-router.js';
 
-export async function handleApiRequest({ request, response, app }) {
+export async function handleApiRequest({
+  request,
+  response,
+  app,
+  system = null,
+  externalKnowledge = null,
+  connectedKnowledge = null
+}) {
   const url = new URL(request.url, 'http://127.0.0.1');
 
   if (url.pathname === '/api/health' && request.method === 'GET') {
@@ -14,120 +21,28 @@ export async function handleApiRequest({ request, response, app }) {
     return true;
   }
 
-  if (app.graphiti) {
-    return handleGraphApiRequest({ request, response, url, app });
-  }
-
-  if (handleLensRequest({ request, response, url, app })) return true;
-
-  if (url.pathname === '/api/state' && request.method === 'GET') {
-    sendJson(response, 200, app.state());
-    return true;
-  }
-
-  if (url.pathname === '/api/spaces' && request.method === 'POST') {
-    const body = await readJson(request);
-    const space = app.createSpace(body.name, body.kind, body.description ?? null);
-    sendJson(response, 200, { space });
-    return true;
-  }
-
-  if (url.pathname === '/api/bootstrap' && request.method === 'POST') {
-    sendJson(response, 200, app.bootstrap());
-    return true;
-  }
-
-  if (url.pathname === '/api/subscriptions' && request.method === 'POST') {
-    const body = await readJson(request);
-    const subscription = app.subscribe(
-      body.personalSpaceId,
-      body.spaceId,
-      body.mode ?? 'latest'
-    );
-    sendJson(response, 200, { subscription });
-    return true;
-  }
-
-  if (url.pathname === '/api/remember' && request.method === 'POST') {
-    const body = await readJson(request);
-    const result = app.remember({
-      personalSpaceId: app.requireSpaceId({
-        id: body.personalSpaceId,
-        name: body.personalSpaceName,
-        label: 'Personal space'
-      }),
-      targetSpaceId: optionalSpaceId(app, {
-        id: body.targetSpaceId,
-        name: body.targetSpaceName,
-        label: 'Target space'
-      }),
-      sourceKind: body.sourceKind ?? 'agent',
-      body: body.body,
-      sourceUri: body.sourceUri ?? null
-    });
-    sendJson(response, 200, result);
-    return true;
-  }
-
-  if (url.pathname === '/api/observe/git-diff' && request.method === 'POST') {
-    const body = await readJson(request);
-    const result = app.observe({
-      personalSpaceId: body.personalSpaceId,
-      targetSpaceId: body.targetSpaceId || null,
-      cwd: body.cwd ?? process.cwd()
-    });
-    sendJson(response, 200, result);
-    return true;
-  }
-
-  const candidateDecisionMatch = url.pathname.match(/^\/api\/candidates\/([^/]+)\/decision$/);
-  if (candidateDecisionMatch && request.method === 'POST') {
-    const body = await readJson(request);
-    const candidate = app.decideCandidate(candidateDecisionMatch[1], body.decision);
-    sendJson(response, 200, { candidate });
+  if (system && url.pathname === '/api/system/settings' && request.method === 'GET') {
+    sendJson(response, 200, system.getSettings());
     return true;
   }
 
-  if (url.pathname === '/api/search' && request.method === 'GET') {
-    const result = app.search({
-      personalSpaceId: requiredSpaceId(app, {
-        id: url.searchParams.get('personalSpaceId'),
-        name: url.searchParams.get('personalSpaceName'),
-        label: 'Personal space'
-      }),
-      query: url.searchParams.get('q') ?? '',
-      includeHistorical: url.searchParams.get('historical') === 'true'
-    });
-    sendJson(response, 200, result);
+  if (system && url.pathname === '/api/system/settings' && request.method === 'PUT') {
+    sendJson(response, 200, system.updateSettings(await readJson(request)));
     return true;
   }
 
-  if (url.pathname === '/api/context-pack' && request.method === 'GET') {
-    const result = app.contextPack({
-      personalSpaceId: requiredSpaceId(app, {
-        id: url.searchParams.get('personalSpaceId'),
-        name: url.searchParams.get('personalSpaceName'),
-        label: 'Personal space'
-      }),
-      spaceId: requiredSpaceId(app, {
-        id: url.searchParams.get('spaceId'),
-        name: url.searchParams.get('spaceName'),
-        label: 'Space'
-      }),
-      query: url.searchParams.get('q') ?? ''
-    });
-    sendJson(response, 200, result);
+  if (system && url.pathname === '/api/system/resources' && request.method === 'GET') {
+    sendJson(response, 200, await system.resources());
     return true;
   }
 
-  return false;
-}
-
-function requiredSpaceId(app, input) {
-  return app.requireSpaceId(input);
-}
+  if (await handleExternalKnowledgeApiRequest({
+    request,
+    response,
+    url,
+    externalKnowledge,
+    connectedKnowledge
+  })) return true;
 
-function optionalSpaceId(app, input) {
-  if (!input.id && !input.name) return null;
-  return requiredSpaceId(app, input);
+  return handleGraphApiRequest({ request, response, url, app });
 }

package/src/http/external-knowledge-api-router.js

@@ -0,0 +1,104 @@
+import { readJson, sendJson } from './response.js';
+
+export async function handleExternalKnowledgeApiRequest({
+  request,
+  response,
+  url,
+  externalKnowledge,
+  connectedKnowledge
+}) {
+  if (!externalKnowledge && !connectedKnowledge) return false;
+
+  if (externalKnowledge &&
+      url.pathname === '/api/external-knowledge/connectors' &&
+      request.method === 'GET') {
+    sendJson(response, 200, externalKnowledge.listConnectorTypes());
+    return true;
+  }
+  if (externalKnowledge &&
+      url.pathname === '/api/external-knowledge/discover' &&
+      request.method === 'POST') {
+    sendJson(response, 200, await externalKnowledge.discover(await readJson(request)));
+    return true;
+  }
+  if (externalKnowledge &&
+      url.pathname === '/api/external-knowledge/bindings' &&
+      request.method === 'GET') {
+    sendJson(response, 200, await externalKnowledge.listBindings());
+    return true;
+  }
+  if (externalKnowledge &&
+      url.pathname === '/api/external-knowledge/bindings' &&
+      request.method === 'POST') {
+    sendJson(response, 201, await externalKnowledge.createBinding(await readJson(request)));
+    return true;
+  }
+
+  const action = url.pathname.match(
+    /^\/api\/external-knowledge\/bindings\/([^/]+)\/(check|sync|retrieve)$/
+  );
+  if (externalKnowledge && action && request.method === 'POST') {
+    const id = decodeURIComponent(action[1]);
+    const body = await readJson(request);
+    const result = action[2] === 'check'
+      ? await externalKnowledge.checkBinding(id)
+      : action[2] === 'sync'
+        ? await externalKnowledge.syncBinding(id, body)
+        : await externalKnowledge.retrieveBinding(id, body);
+    sendJson(response, 200, result);
+    return true;
+  }
+
+  const targets = url.pathname.match(
+    /^\/api\/external-knowledge\/bindings\/([^/]+)\/targets$/
+  );
+  if (externalKnowledge && targets && request.method === 'PATCH') {
+    sendJson(
+      response,
+      200,
+      await externalKnowledge.updateBindingTargets(
+        decodeURIComponent(targets[1]),
+        await readJson(request)
+      )
+    );
+    return true;
+  }
+
+  const binding = url.pathname.match(
+    /^\/api\/external-knowledge\/bindings\/([^/]+)$/
+  );
+  if (externalKnowledge && binding && request.method === 'DELETE') {
+    sendJson(
+      response,
+      200,
+      await externalKnowledge.deleteBinding(decodeURIComponent(binding[1]))
+    );
+    return true;
+  }
+
+  if (connectedKnowledge &&
+      url.pathname === '/api/external-knowledge/conflict-policy' &&
+      request.method === 'GET') {
+    sendJson(response, 200, connectedKnowledge.getConflictPolicy({
+      personalProjectId: url.searchParams.get('personalProjectId')
+    }));
+    return true;
+  }
+  if (connectedKnowledge &&
+      url.pathname === '/api/external-knowledge/conflict-policy' &&
+      request.method === 'PATCH') {
+    sendJson(
+      response,
+      200,
+      await connectedKnowledge.updateConflictPolicy(await readJson(request))
+    );
+    return true;
+  }
+  if (connectedKnowledge &&
+      url.pathname === '/api/connected-knowledge/search' &&
+      request.method === 'POST') {
+    sendJson(response, 200, await connectedKnowledge.query(await readJson(request)));
+    return true;
+  }
+  return false;
+}

package/src/http/graph-api-router.js

@@ -44,7 +44,8 @@ export async function handleGraphApiRequest({ request, response, url, app }) {
       spaceId: url.searchParams.get('spaceId'),
       providerUrl: url.searchParams.get('providerUrl'),
       personalProjectId: url.searchParams.get('personalProjectId'),
-      limit: numberParam(url, 'limit', 500)
+      limit: numberParam(url, 'limit', 500),
+      offset: nonNegativeNumberParam(url, 'offset', null)
     }));
     return true;
   }
@@ -255,3 +256,13 @@ function numberParam(url, name, fallback) {
   }
   return value;
 }
+
+function nonNegativeNumberParam(url, name, fallback) {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative integer`);
+  }
+  return value;
+}

package/src/http/request-policy.js

@@ -1,3 +1,5 @@
+import { timingSafeEqual } from 'node:crypto';
+
 import { sendJson } from './response.js';
 
 export function localServerAuthority(address) {
@@ -9,18 +11,38 @@ export function localServerAuthority(address) {
 }
 
 export function rejectDisallowedRequest({ request, response, authority }) {
+  return rejectRequestOutsidePolicy({ request, response, authority });
+}
+
+export function rejectRequestOutsidePolicy({
+  request,
+  response,
+  authority,
+  lanAuthorities = [],
+  lanAccessToken = null
+}) {
   const origin = request.headers.origin;
   const fetchSite = request.headers['sec-fetch-site'];
+  const requestAuthority = request.headers.host;
+  const lanRequest = lanAuthorities.includes(requestAuthority);
+  const loopbackRequest = requestAuthority === authority;
   if (
     !authority ||
-    request.headers.host !== authority ||
-    (origin !== undefined && origin !== `http://${authority}`) ||
+    (requestAuthority !== authority && !lanRequest) ||
+    (lanAuthorities.length > 0 && loopbackRequest && !isLoopbackAddress(request.socket?.remoteAddress)) ||
+    (origin !== undefined && origin !== `http://${requestAuthority}`) ||
     (typeof fetchSite === 'string' && fetchSite.toLowerCase() === 'cross-site')
   ) {
     sendJson(response, 403, { error: 'Forbidden' });
     return true;
   }
 
+  if (lanRequest && !hasLanAccess(request.headers.authorization, lanAccessToken)) {
+    response.setHeader('www-authenticate', 'Basic realm="FULI LAN", charset="UTF-8"');
+    sendJson(response, 401, { error: 'LAN access code required' });
+    return true;
+  }
+
   if (requiresJson(request) && !isJson(request.headers['content-type'])) {
     sendJson(response, 415, { error: 'Unsupported media type' });
     return true;
@@ -29,8 +51,21 @@ export function rejectDisallowedRequest({ request, response, authority }) {
   return false;
 }
 
+function hasLanAccess(authorization, accessToken) {
+  if (typeof accessToken !== 'string' || !accessToken) return false;
+  const expected = `Basic ${Buffer.from(`fuli:${accessToken}`).toString('base64')}`;
+  if (typeof authorization !== 'string' || authorization.length !== expected.length) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(authorization), Buffer.from(expected));
+}
+
+function isLoopbackAddress(address) {
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
 function requiresJson(request) {
-  if (request.method !== 'POST') return false;
+  if (!['PATCH', 'POST', 'PUT'].includes(request.method)) return false;
   const pathname = new URL(request.url, 'http://127.0.0.1').pathname;
   return pathname.startsWith('/api/');
 }