fuli-context 0.7.4-beta.2 → 0.7.5

package/src/cli/workspace-connection-command.js

@@ -0,0 +1,333 @@
+import {
+  chmodSync,
+  lstatSync,
+  readFileSync,
+  writeFileSync
+} from 'node:fs';
+
+import {
+  canonicalProviderUrl,
+  GraphRuntimeConfigurationError
+} from '../graphiti/runtime-config.js';
+import { resolveSetupPaths } from '../setup/paths.js';
+import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
+
+const HELP_FLAGS = new Set(['--help', '-h']);
+const VALUE_FLAGS = new Set(['--url', '--token-file', '--data-dir']);
+const WORKSPACE_ROLES = new Set(['reader', 'contributor', 'maintainer', 'admin']);
+const MAX_HANDSHAKE_BYTES = 64 * 1024;
+const MAX_TOKEN_BYTES = 4096;
+
+export class WorkspaceConnectionError extends Error {}
+
+export async function runWorkspaceConnectionCommand(args, dependencies = {}) {
+  const options = parseWorkspaceConnectionOptions(args);
+  const write = dependencies.write ?? writeLine;
+  if (options.help) {
+    write(workspaceConnectionHelp());
+    return { status: 'help' };
+  }
+
+  const providerUrl = normalizeProviderUrl(options.url);
+  const token = readSecureToken(options.tokenFile, dependencies);
+  const fetchImpl = dependencies.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new WorkspaceConnectionError('This Node.js runtime does not provide fetch.');
+  }
+
+  const discovery = await requestJson({
+    fetchImpl,
+    url: new URL('/.well-known/fuli-workspace', `${providerUrl}/`),
+    expectedOrigin: new URL(providerUrl).origin,
+    timeoutMs: dependencies.timeoutMs
+  });
+  const provider = validateDiscovery(discovery, providerUrl);
+  const session = await requestJson({
+    fetchImpl,
+    url: provider.authSessionUrl,
+    expectedOrigin: new URL(providerUrl).origin,
+    token,
+    timeoutMs: dependencies.timeoutMs
+  });
+  const identity = validateSession(session);
+
+  const resolvePaths = dependencies.resolvePaths ?? resolveSetupPaths;
+  const paths = resolvePaths({ dataDir: options.dataDir, env: dependencies.env ?? process.env });
+  const runtimeConfigPath = paths.graphRuntimeConfigPath;
+  const readConfig = dependencies.readConfig ?? readJsonFile;
+  let runtimeConfig;
+  try {
+    runtimeConfig = readConfig(runtimeConfigPath, null);
+  } catch {
+    throw new WorkspaceConnectionError('Could not read the Fuli runtime configuration.');
+  }
+  if (runtimeConfig?.version !== 1 || !runtimeConfig.personal
+      || !Array.isArray(runtimeConfig.workspaces)) {
+    throw new WorkspaceConnectionError('Fuli is not initialized. Run `fuli setup` first.');
+  }
+
+  const workspace = {
+    protocol: 'fuli-workspace-v1',
+    providerUrl,
+    providerId: provider.id,
+    accessToken: token,
+    principalId: identity.principalId,
+    role: identity.role,
+    workspaceIds: identity.workspaceIds
+  };
+  const nextConfig = {
+    ...runtimeConfig,
+    workspaces: upsertWorkspace(runtimeConfig.workspaces, workspace)
+  };
+  const writeConfig = dependencies.writeConfig ?? writeSecureJson;
+  const secureFile = dependencies.secureFile ?? ((path) => chmodSync(path, 0o600));
+  try {
+    writeConfig(runtimeConfigPath, nextConfig);
+    secureFile(runtimeConfigPath);
+  } catch {
+    throw new WorkspaceConnectionError('Could not update the Fuli runtime configuration.');
+  }
+
+  write([
+    `Shared workspace service configured: ${providerUrl}`,
+    'Restart required: run `fuli restart` to apply this connection.'
+  ].join('\n'));
+  return { status: 'configured', providerUrl, restartRequired: true };
+}
+
+export function parseWorkspaceConnectionOptions(args) {
+  if (!Array.isArray(args)) throw new WorkspaceConnectionError('Command arguments are invalid.');
+  if (args.some((argument) => HELP_FLAGS.has(argument))) {
+    if (args.length !== 1) {
+      throw new WorkspaceConnectionError('The help flag cannot be combined with other options.');
+    }
+    return { help: true, url: null, tokenFile: null, dataDir: null };
+  }
+
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    if (!VALUE_FLAGS.has(flag)) {
+      throw new WorkspaceConnectionError('Unknown option for connect-workspace.');
+    }
+    if (values.has(flag)) {
+      throw new WorkspaceConnectionError(`Duplicate connect-workspace option: ${flag}`);
+    }
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new WorkspaceConnectionError(`Missing value for ${flag}`);
+    }
+    values.set(flag, value.trim());
+  }
+
+  if (!values.has('--url')) {
+    throw new WorkspaceConnectionError('Missing required option: --url');
+  }
+  if (!values.has('--token-file')) {
+    throw new WorkspaceConnectionError('Missing required option: --token-file');
+  }
+  return {
+    help: false,
+    url: values.get('--url'),
+    tokenFile: values.get('--token-file'),
+    dataDir: values.get('--data-dir') ?? null
+  };
+}
+
+export function workspaceConnectionHelp() {
+  return [
+    'Usage: fuli connect-workspace --url URL --token-file FILE [--data-dir DIR]',
+    '',
+    'Validates a Fuli Workspace service and stores its bearer token in the local',
+    'Fuli runtime configuration. Restart Fuli after the command succeeds.'
+  ].join('\n');
+}
+
+function normalizeProviderUrl(value) {
+  try {
+    return new URL(canonicalProviderUrl(value)).origin;
+  } catch (error) {
+    if (error instanceof GraphRuntimeConfigurationError) {
+      throw new WorkspaceConnectionError(error.message);
+    }
+    throw new WorkspaceConnectionError('Workspace service URL is invalid.');
+  }
+}
+
+function readSecureToken(path, dependencies) {
+  const inspect = dependencies.lstat ?? lstatSync;
+  const readText = dependencies.readText ?? ((filePath) => readFileSync(filePath, 'utf8'));
+  let metadata;
+  try {
+    metadata = inspect(path);
+  } catch {
+    throw new WorkspaceConnectionError('The token file could not be inspected.');
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    throw new WorkspaceConnectionError('The token file must be a regular file, not a symlink.');
+  }
+  const platform = dependencies.platform ?? process.platform;
+  if (platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+    throw new WorkspaceConnectionError('The token file must not be readable by group or other users.');
+  }
+  if (!Number.isFinite(metadata.size) || metadata.size < 1 || metadata.size > MAX_TOKEN_BYTES) {
+    throw new WorkspaceConnectionError('The token file has an invalid size.');
+  }
+
+  let token;
+  try {
+    token = readText(path).trim();
+  } catch {
+    throw new WorkspaceConnectionError('The token file could not be read.');
+  }
+  if (token.length < 20 || token.length > MAX_TOKEN_BYTES || !/^[\x21-\x7e]+$/u.test(token)) {
+    throw new WorkspaceConnectionError('The token file does not contain a valid bearer token.');
+  }
+  return token;
+}
+
+async function requestJson({ fetchImpl, url, expectedOrigin, token = null, timeoutMs = 5000 }) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json',
+        ...(token ? { authorization: `Bearer ${token}` } : {})
+      },
+      redirect: 'manual',
+      cache: 'no-store',
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch {
+    throw new WorkspaceConnectionError('Could not reach the workspace service.');
+  }
+  if (response.status >= 300 && response.status < 400) {
+    throw new WorkspaceConnectionError('Workspace service redirects are not allowed during connection.');
+  }
+  if (response.url) {
+    let responseOrigin;
+    try {
+      responseOrigin = new URL(response.url).origin;
+    } catch {
+      throw new WorkspaceConnectionError('Workspace service returned an invalid response URL.');
+    }
+    if (responseOrigin !== expectedOrigin) {
+      throw new WorkspaceConnectionError('Workspace service returned a cross-origin response.');
+    }
+  }
+  if (!response.ok) {
+    throw new WorkspaceConnectionError(`Workspace service rejected the connection (HTTP ${response.status}).`);
+  }
+
+  let text;
+  try {
+    text = await response.text();
+  } catch {
+    throw new WorkspaceConnectionError('Workspace service returned an unreadable response.');
+  }
+  if (Buffer.byteLength(text, 'utf8') > MAX_HANDSHAKE_BYTES) {
+    throw new WorkspaceConnectionError('Workspace service response is too large.');
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new WorkspaceConnectionError('Workspace service did not return valid JSON.');
+  }
+}
+
+function validateDiscovery(discovery, providerUrl) {
+  if (String(discovery?.protocolVersion ?? '') !== '1') {
+    throw new WorkspaceConnectionError('Workspace service protocol version is not supported.');
+  }
+  const id = safeIdentifier(discovery?.provider?.id, 'Workspace service provider ID is invalid.');
+  const advertised = discovery?.endpoints?.authSession ?? '/v1/auth/session';
+  const authSessionUrl = sameOriginEndpoint(advertised, providerUrl);
+  return { id, authSessionUrl };
+}
+
+function validateSession(session) {
+  if (session?.authenticated !== true) {
+    throw new WorkspaceConnectionError('The workspace service did not authenticate this token.');
+  }
+  const principalId = safeIdentifier(
+    session?.principal?.id,
+    'Workspace service returned an invalid principal.'
+  );
+  const grant = session?.grant && typeof session.grant === 'object' ? session.grant : session;
+  const role = String(grant?.role ?? '');
+  if (!WORKSPACE_ROLES.has(role)) {
+    throw new WorkspaceConnectionError('Workspace service returned an unsupported role.');
+  }
+  const workspaceIds = normalizeWorkspaceIds(grant?.workspaceIds);
+  return { principalId, role, workspaceIds };
+}
+
+function normalizeWorkspaceIds(value) {
+  if (value === '*') return '*';
+  if (!Array.isArray(value)) {
+    throw new WorkspaceConnectionError('Workspace service returned an invalid workspace grant.');
+  }
+  return value.map((id) => safeIdentifier(id, 'Workspace service returned an invalid workspace grant.'));
+}
+
+function safeIdentifier(value, message) {
+  if (typeof value !== 'string') throw new WorkspaceConnectionError(message);
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 256 || /[\u0000-\u001f\u007f]/u.test(normalized)) {
+    throw new WorkspaceConnectionError(message);
+  }
+  return normalized;
+}
+
+function sameOriginEndpoint(value, providerUrl) {
+  let endpoint;
+  try {
+    endpoint = new URL(String(value), `${providerUrl}/`);
+  } catch {
+    throw new WorkspaceConnectionError('Workspace service advertised an invalid authentication endpoint.');
+  }
+  const providerOrigin = new URL(providerUrl).origin;
+  if (endpoint.origin !== providerOrigin || endpoint.username || endpoint.password
+      || endpoint.search || endpoint.hash) {
+    throw new WorkspaceConnectionError('Workspace service advertised a cross-origin authentication endpoint.');
+  }
+  return endpoint;
+}
+
+function upsertWorkspace(workspaces, workspace) {
+  const next = [];
+  let replaced = false;
+  for (const existing of workspaces) {
+    if (!sameProvider(existing?.providerUrl, workspace.providerUrl)) {
+      next.push(existing);
+      continue;
+    }
+    if (!replaced) next.push({ ...existing, ...workspace });
+    replaced = true;
+  }
+  if (!replaced) next.push(workspace);
+  return next;
+}
+
+function sameProvider(left, right) {
+  try {
+    return new URL(canonicalProviderUrl(left)).origin === right;
+  } catch {
+    return false;
+  }
+}
+
+function writeSecureJson(path, value) {
+  writeJsonFileAtomic(path, value, {
+    writeFileSync: (temporaryPath, payload, options) => writeFileSync(
+      temporaryPath,
+      payload,
+      { ...options, mode: 0o600 }
+    )
+  });
+}
+
+function writeLine(value) {
+  process.stdout.write(`${value}\n`);
+}

package/src/cli.js

@@ -7,9 +7,11 @@ import {
   printHelp
 } from './cli/command-registry.js';
 import { runLocalRuntimeCommand } from './cli/local-runtime-command.js';
+import { runGraphDataCommand } from './cli/graph-data-command.js';
 import { runSetupCommand } from './cli/setup-command.js';
 import { runUninstallCommand } from './cli/uninstall-command.js';
 import { runUpdateCommand } from './cli/update-command.js';
+import { runWorkspaceConnectionCommand } from './cli/workspace-connection-command.js';
 import { FULI_VERSION } from './package-metadata.js';
 import { assertSupportedNodeVersion } from './setup/node-runtime.js';
 
@@ -28,6 +30,15 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
     await runSetupCommand(commandArgs, { env });
     return;
   }
+  if (command === 'graph') {
+    assertSupportedNodeVersion();
+    const [action, ...graphArgs] = commandArgs;
+    return runGraphDataCommand(action, graphArgs, { env });
+  }
+  if (command === 'connect-workspace') {
+    assertSupportedNodeVersion();
+    return runWorkspaceConnectionCommand(commandArgs, { env });
+  }
   if (command === 'uninstall') {
     await runUninstallCommand(commandArgs, { env });
     return;

package/src/graphiti/collaboration-preference-projection.js

@@ -10,6 +10,9 @@ export function agentCollaborationPreference(item) {
   if (item.preference_project_id) {
     preference.preference_project_id = item.preference_project_id;
   }
+  if (item.preference_agent_id) {
+    preference.preference_agent_id = item.preference_agent_id;
+  }
   for (const field of [
     'attributes',
     'weight',
@@ -27,10 +30,31 @@ export function agentCollaborationPreference(item) {
   return preference;
 }
 
+export function activePreferenceConflicts(result) {
+  const items = [
+    ...(result.global_preferences ?? []),
+    ...(result.project_preferences ?? []),
+    ...(result.agent_preferences ?? [])
+  ];
+  const itemById = new Map(items.map((item) => [item.id, item]));
+  return (result.conflicts ?? []).map((conflict) => ({
+    preference_key: conflict.preference_key,
+    preference_scope: conflict.preference_scope,
+    preference_project_id: conflict.preference_project_id ?? null,
+    preference_agent_id: conflict.preference_agent_id ?? null,
+    alternatives: (conflict.item_ids ?? [])
+      .map((id) => itemById.get(id))
+      .filter(Boolean)
+      .map(agentCollaborationPreference),
+    required_action: 'Do not apply any alternative until the conflict is resolved.'
+  }));
+}
+
 export function deferredPreferenceConflicts(result, queuedConflicts) {
   const items = [
     ...(result.global_preferences ?? []),
-    ...(result.project_preferences ?? [])
+    ...(result.project_preferences ?? []),
+    ...(result.agent_preferences ?? [])
   ];
   const itemById = new Map(items.map((item) => [item.id, item]));
   const activeConflictPairs = new Set(
@@ -121,6 +145,9 @@ export function agentDeferredPreferenceConflict(conflict) {
     ...(conflict.preference_project_id
       ? { preference_project_id: conflict.preference_project_id }
       : {}),
+    ...(conflict.preference_agent_id
+      ? { preference_agent_id: conflict.preference_agent_id }
+      : {}),
     status: conflict.status,
     deferred_at: conflict.deferred_at,
     reason: conflict.reason,
@@ -142,6 +169,7 @@ function agentConflictPreference(item) {
   };
   for (const field of [
     'preference_project_id',
+    'preference_agent_id',
     'inherited_from_project_id',
     'scope_distance',
     'scope_path',

package/src/graphiti/collaboration-preference-workflow.js

@@ -0,0 +1,121 @@
+import {
+  agentProjectResolution
+} from './agent-knowledge-workflows.js';
+import {
+  activePreferenceConflicts,
+  agentCollaborationPreference,
+  agentDeferredPreferenceConflict,
+  deferredPreferenceConflicts
+} from './collaboration-preference-projection.js';
+import {
+  recallTaskKnowledge,
+  TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE
+} from './task-knowledge-recall.js';
+
+export async function getCollaborationPreferences(
+  application,
+  projectResolution,
+  {
+    projectAgentId = null,
+    taskPrompt = null,
+    limit = 100,
+    agentInvocation = false,
+    agentToolName = 'get_collaboration_preferences'
+  },
+  recordAgentViews
+) {
+  const resolvedProjectId = projectResolution.personalProjectId;
+  const [result, queuedConflicts] = await Promise.all([
+    application.personal.collaborationPreferences(
+      application.config.personal.spaceId,
+      resolvedProjectId,
+      limit,
+      projectAgentId
+    ),
+    application.personal.listPreferenceConflicts(
+      application.config.personal.spaceId,
+      'ai_pending',
+      limit
+    )
+  ]);
+  const deferredConflicts = deferredPreferenceConflicts(
+    result,
+    queuedConflicts
+  );
+  const taskKnowledgeRecall = taskPrompt === null
+    ? null
+    : await recallTaskKnowledge(application, projectResolution, taskPrompt);
+  if (agentInvocation) {
+    const items = [
+      ...(result.global_preferences ?? []),
+      ...(result.project_preferences ?? []),
+      ...(result.agent_preferences ?? [])
+    ];
+    await recordAgentViews(items.map(({ id, item_kind: itemKind }) => ({
+      item_id: id,
+      item_kind: itemKind
+    })), agentToolName);
+  }
+  const applicationGuidance = guidanceFor(
+    resolvedProjectId,
+    projectAgentId
+  );
+  if (!agentInvocation) {
+    return {
+      ...result,
+      deferred_conflicts: deferredConflicts,
+      application_guidance: applicationGuidance,
+      project_resolution: agentProjectResolution(projectResolution),
+      ...(taskKnowledgeRecall ? { task_knowledge_recall: taskKnowledgeRecall } : {})
+    };
+  }
+  return {
+    effective_preferences: (result.effective_preferences ?? [])
+      .map(agentCollaborationPreference),
+    deferred_conflicts: deferredConflicts.map(agentDeferredPreferenceConflict),
+    active_conflicts: activePreferenceConflicts(result),
+    application_guidance: applicationGuidance,
+    ...(taskKnowledgeRecall ? { task_knowledge_recall: taskKnowledgeRecall } : {}),
+    context: preferenceContext(result, deferredConflicts, projectResolution)
+  };
+}
+
+function guidanceFor(projectId, projectAgentId) {
+  return {
+    apply: 'effective_preferences',
+    global_scope: 'Apply personal-global preferences in every user task.',
+    project_scope: projectId
+      ? `Also apply preferences scoped to ${projectId} and confirmed ancestor preferences whose descendants or selected-projects mode explicitly reaches it.`
+      : 'No exact personal project matched; do not apply project-scoped preferences.',
+    agent_scope: projectAgentId
+      ? `Also apply preferences scoped to project Agent ${projectAgentId}; exclude every other project Agent.`
+      : 'No project Agent was selected; do not apply Agent-scoped preferences.',
+    inheritance: 'Project preference inheritance follows only PART_OF or USES_KNOWLEDGE_FROM for at most two hops. Preserve inherited_from_project_id, scope_path, and scope_distance. An exact item wins only after confirmation authority is compared; weight never expands scope or resolves a conflict.',
+    related_projects: 'RELATED_TO preferences never auto-apply. Use structured related-project suggestions to ask before a one-time read-only expansion.',
+    conflicts: 'Do not apply entries listed in conflicts until the user resolves them.',
+    deferred_conflicts: 'If the current task would use a deferred_conflict, call resolve_deferred_preference_conflict before applying either side. Ignore unrelated deferred conflicts. The resolution must preserve the AI audit marker.',
+    authority: 'Human or authoritative-source confirmed preferences outrank agent-confirmed preferences. Agent-confirmed preferences are usable but lower priority and remain explicitly marked.',
+    pending: 'Pending preferences are available only through on-demand knowledge search; invalid and unrelated-project preferences are excluded. Automatic preference injection does not count as usage evidence.',
+    knowledge_retrieval: TASK_KNOWLEDGE_RETRIEVAL_GUIDANCE
+  };
+}
+
+function preferenceContext(result, deferredConflicts, projectResolution) {
+  return {
+    personal_space_id: result.personal_space_id,
+    personal_project_id: result.personal_project_id,
+    project_agent_id: result.project_agent_id ?? null,
+    global_preference_count: (result.global_preferences ?? []).length,
+    project_preference_count: (result.project_preferences ?? []).length,
+    inherited_project_preference_count: (result.project_preferences ?? [])
+      .filter(({ inherited_from_project_id: projectId }) => Boolean(projectId))
+      .length,
+    agent_preference_count: (result.agent_preferences ?? []).length,
+    conflict_count: (result.conflicts ?? []).length,
+    ai_deferred_conflict_count: deferredConflicts.length,
+    overridden_global_count: (result.overridden_global_ids ?? []).length,
+    overridden_project_count: (result.overridden_project_ids ?? []).length,
+    source_truncated: result.truncated === true,
+    project_resolution: agentProjectResolution(projectResolution)
+  };
+}