fuli-context 0.7.6 → 0.7.8

package/src/graphiti/agent-knowledge-workflows.js

@@ -1,5 +1,8 @@
 import { createHash } from 'node:crypto';
 
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+import { agentMemoryRecord, prepareProjectAgentMemory } from './project-agent-memory.js';
+
 import { onlineSourceUri } from './source-uri.js';
 import {
   relatedProjectGuidance,
@@ -8,28 +11,58 @@ import {
 
 export async function beginTaskContext(application, {
   sessionId,
+  turnId = null,
   projectPath,
-  taskPrompt = null
+  personalProjectId = null,
+  taskPrompt = null,
+  sourceApplication = 'other',
+  sourceSessionId = null,
+  projectAgentId = null,
+  workKind = null,
+  requiredCapabilities = []
 }) {
+  const continuationToken = /^FULI_CHECKPOINT_REQUIRED: (fuli-task-[a-zA-Z0-9-]{8,128})\b/.exec(taskPrompt ?? '')?.[1];
+  const resumed = continuationToken
+    ? await application.taskContextRegistry.context(continuationToken, sourceApplication) : null;
+  if (resumed && resumed.sessionId !== sessionId) {
+    throw validationError('Checkpoint continuation belongs to another host session');
+  }
   const preferences = await application.getCollaborationPreferences({
+    personalProjectId,
     projectPath,
+    sessionId,
+    turnId,
     taskPrompt,
+    projectAgentId: resumed?.projectAgentId ?? projectAgentId,
+    sourceApplication,
+    sourceSessionId,
+    workKind,
+    requiredCapabilities,
     agentInvocation: true,
     agentToolName: 'begin_task_context'
   });
-  const task = application.taskContextRegistry.begin({
+  if (resumed && resumed.personalProjectId !== preferences.context.personal_project_id) {
+    throw validationError('Checkpoint continuation belongs to another project');
+  }
+  const task = resumed ?? await application.taskContextRegistry.begin({
     sessionId,
-    personalProjectId: preferences.context.personal_project_id
+    turnId,
+    personalProjectId: preferences.context.personal_project_id,
+    projectAgentId: preferences.context.project_agent_id,
+    sourceApplication,
+    sourceSessionId,
+    memoryRevision: preferences.project_agent_context?.memory?.revision ?? null
   });
   return {
     taskContextToken: task.token,
     task_context_token: task.token,
-    checkpoint_required: true,
+    checkpoint_required: task.checkpoint?.phase !== 'complete',
+    resumed_checkpoint: Boolean(resumed),
     previous_checkpoint_missing: task.previousCheckpointMissing,
     ...preferences,
     task_guidance: {
       retrieval: 'Inspect task_knowledge_recall before asking for a stable project fact or method again. On a miss, use search_current_project_knowledge with focused action, artifact, target-system, or identifier queries; never use the full conversational request as the only query.',
-      checkpoint: 'Before finishing, call checkpoint_task_knowledge with capture_candidates or retain_nothing.'
+      checkpoint: 'Before finishing, call checkpoint_task_knowledge with capture_candidates or retain_nothing. When durable role context changed, include agentMemory with the loaded revision and a bounded merged summary, decisions, open threads and next actions. Do not overwrite from truncated context or store raw transcripts.'
     }
   };
 }
@@ -38,43 +71,120 @@ export async function checkpointTaskKnowledge(application, {
   taskContextToken,
   disposition,
   reason,
-  capture = null
+  capture = null,
+  agentMemory = null,
+  sourceApplication = 'other',
+  personalProjectId = null,
+  remoteSessionId = null
 }) {
   if (!['capture_candidates', 'retain_nothing'].includes(disposition)) {
-    throw new TypeError('Unknown task knowledge checkpoint disposition');
+    throw validationError('Unknown task knowledge checkpoint disposition');
+  }
+  const task = await application.taskContextRegistry.context(taskContextToken, sourceApplication);
+  if (personalProjectId && task.personalProjectId !== personalProjectId) {
+    throw validationError('Task checkpoint belongs to another project');
+  }
+  if (remoteSessionId && task.sessionId !== remoteSessionId) {
+    throw validationError('Task checkpoint belongs to another remote session');
   }
-  const task = application.taskContextRegistry.context(taskContextToken);
-
-  let captureResult = null;
   if (disposition === 'capture_candidates') {
     if (!capture) {
-      throw new TypeError('capture_candidates requires a bounded capture payload');
+      throw validationError('capture_candidates requires a bounded capture payload');
+    }
+  } else if (capture) {
+    throw validationError('retain_nothing cannot include a capture payload');
+  }
+  const fingerprint = createHash('sha256').update(JSON.stringify(
+    canonicalCheckpoint({ disposition, reason, capture, agentMemory })
+  )).digest('hex');
+  if (task.checkpoint && task.checkpoint.fingerprint !== fingerprint) {
+    throw validationError(
+      'Task checkpoint already has different input; resume the original review or begin a new task context'
+    );
+  }
+  if (task.checkpoint?.phase === 'complete') {
+    return { status: 'checkpointed', disposition, reason,
+      personal_project_id: task.personalProjectId, project_agent_id: task.projectAgentId,
+      replayed: true, capture_status: task.checkpoint.captureStatus };
+  }
+  const captureInput = capture ? {
+    ...capture,
+    targetKind: 'personal',
+    spaceId: application.config.personal.spaceId,
+    personalProjectId: task.personalProjectId,
+    projectAgentId: task.projectAgentId ?? null,
+    sessionId: task.sessionId,
+    sourceApplication,
+    idempotencyKey: `${task.token}:knowledge`
+  } : null;
+  // Local validation has no side effects. Reject correctable input before
+  // binding an immutable checkpoint or advancing the Agent's memory revision.
+  if (captureInput) application.validateCaptureSessionKnowledge(captureInput);
+  let memoryResult = null;
+  let memoryRequest = null;
+  if (agentMemory) {
+    if (!task.projectAgentId || !task.personalProjectId) {
+      throw validationError('Task has no durable project Agent; do not guess a memory target');
     }
-    captureResult = await application.captureSessionKnowledge({
-      targetKind: 'personal',
-      spaceId: application.config.personal.spaceId,
+    const prepared = await prepareProjectAgentMemory(application, {
+      personalSpaceId: application.config.personal.spaceId,
       personalProjectId: task.personalProjectId,
-      sessionId: task.sessionId,
-      ...capture
+      agentId: task.projectAgentId,
+      expectedRevision: agentMemory.expectedRevision,
+      idempotencyKey: `${task.token}:memory`,
+      memory: agentMemory.memory, sourceApplication,
+      // The logical client session survives independent lifecycle-hook MCP
+      // processes; their host session ids do not. The Provider persists this
+      // stable task session as the memory checkpoint provenance.
+      sourceSessionId: task.sessionId
     });
-  } else if (capture) {
-    throw new TypeError('retain_nothing cannot include a capture payload');
+    if (prepared.status === 'capture_disabled') memoryResult = prepared;
+    else memoryRequest = { expected_revision: prepared.request.expected_revision,
+      memory: prepared.request.memory };
   }
-
-  application.taskContextRegistry.checkpoint(taskContextToken, {
-    disposition,
-    reason,
-    captureStatus: captureResult?.status ?? null
-  });
+  const checkpoint = { disposition, reason, fingerprint, captureStatus: null };
+  const preparedTask = await application.taskContextRegistry.prepare(
+    taskContextToken, checkpoint, sourceApplication, memoryRequest
+  );
+  if (memoryRequest) {
+    if (!preparedTask.agentMemory) {
+      throw new TypeError('Provider did not confirm atomic Agent memory preparation');
+    }
+    memoryResult = { status: 'checkpointed', ...agentMemoryRecord(preparedTask.agentMemory) };
+  }
+  const captureResult = captureInput
+    ? await application.captureSessionKnowledge(captureInput) : null;
+  await application.taskContextRegistry.checkpoint(taskContextToken, {
+    ...checkpoint, captureStatus: captureResult?.status ?? null
+  }, sourceApplication);
   return {
     status: 'checkpointed',
     disposition,
     reason,
     personal_project_id: task.personalProjectId,
-    capture: captureResult
+    project_agent_id: task.projectAgentId ?? null,
+    capture: captureResult,
+    agent_memory: memoryResult ? {
+      status: memoryResult.status, agentId: memoryResult.agentId,
+      checkpointId: memoryResult.checkpointId, revision: memoryResult.revision,
+      sourceApplication: memoryResult.sourceApplication,
+      sourceSessionId: memoryResult.sourceSessionId, createdAt: memoryResult.createdAt
+    } : null
   };
 }
 
+function canonicalCheckpoint(value) {
+  if (Array.isArray(value)) return value.map(canonicalCheckpoint);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [
+    key, canonicalCheckpoint(value[key])
+  ]));
+}
+
+function validationError(message) {
+  return new ApplicationError(ApplicationErrorCode.VALIDATION, message);
+}
+
 export async function recordDecisionTrace(application, input) {
   const trace = decisionTraceKnowledge(input);
   return application.captureSessionKnowledge({

package/src/graphiti/federated-application.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { createEmployeeService } from '../employees/service.js';
 
 import { GraphitiProviderClient } from './provider-client.js';
 import {
@@ -30,7 +31,7 @@ import {
 } from './source-marker.js';
 import { resolvePersonalProjectPath } from './project-path-context.js';
 import { mergeExternalKnowledgeProjection } from '../external-knowledge/graph-projection.js';
-import { TaskContextRegistry } from '../mcp/task-context-registry.js';
+import { ProviderTaskContextRegistry } from '../mcp/provider-task-context-registry.js';
 import { attachExternalKnowledgeRuntime } from '../external-knowledge/runtime.js';
 import { resolveSetupPaths } from '../setup/paths.js';
 import {
@@ -79,6 +80,7 @@ import {
   getCollaborationPreferences as getCollaborationPreferencesWorkflow
 } from './collaboration-preference-workflow.js';
 import { buildUserTasteSkill } from './user-taste-skill.js';
+import { resolveTaskEntryAgent, loadProjectAgentContinuity } from './project-agent-task-entry.js';
 import { getWritingTasteProfile as getWritingTasteProfileWorkflow } from './writing-taste-profile-workflow.js';
 import {
   groupSubscriptions,
@@ -114,6 +116,7 @@ export function openFederatedGraphApplication({
       env,
       fetchImpl
     });
+    app.employees = createEmployeeService({ app, runtimeConfigPath });
   }
   return app;
 }
@@ -137,7 +140,7 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     agentAccessPolicyStore = new AgentAccessPolicyStore(),
     consoleUrl = sourceConsoleUrl(null),
     projectPathResolver = resolvePersonalProjectPath,
-    taskContextRegistry = new TaskContextRegistry(),
+    taskContextRegistry = null,
     providerRequestTimeoutMs = undefined
   } = {}) {
     super();
@@ -147,7 +150,6 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     this.agentAccessPolicyStore = agentAccessPolicyStore;
     this.consoleUrl = consoleUrl;
     this.projectPathResolver = projectPathResolver;
-    this.taskContextRegistry = taskContextRegistry;
     this.personal = new GraphitiProviderClient({
       baseUrl: config.personal.providerUrl,
       accessToken: config.personal.accessToken,
@@ -155,6 +157,9 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
       fetchImpl,
       requestTimeoutMs: providerRequestTimeoutMs
     });
+    this.taskContextRegistry = taskContextRegistry ?? new ProviderTaskContextRegistry(
+      this.personal, config.personal.spaceId
+    );
     this.workspaces = new Map(config.workspaces.map((workspace) => {
       const provider = createWorkspaceProvider(workspace, {
         fetchImpl, requestTimeoutMs: providerRequestTimeoutMs
@@ -171,8 +176,8 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     return checkpointTaskKnowledgeWorkflow(this, input);
   }
 
-  verifyTaskCheckpoint({ sessionId }) {
-    return this.taskContextRegistry.verify(sessionId);
+  verifyTaskCheckpoint({ sessionId, sourceApplication = 'other' }) {
+    return this.taskContextRegistry.verify(sessionId, sourceApplication);
   }
 
   async recordDecisionTrace(input) {
@@ -180,6 +185,10 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     return recordDecisionTraceWorkflow(this, input);
   }
 
+  validateCaptureSessionKnowledge(input) {
+    if (this.getCapturePolicy().enabled) this.#prepareKnowledgeCapture(input);
+  }
+
   async captureSessionKnowledge(input) {
     const capturePolicy = this.getCapturePolicy();
     if (!capturePolicy.enabled) {
@@ -189,15 +198,8 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
         capturePolicy
       };
     }
-    assertNoCredentials(input);
-    const episode = providerEpisode(input);
+    const { episode, workspace } = this.#prepareKnowledgeCapture(input);
     if (input.targetKind === 'personal') {
-      if (input.spaceId !== this.config.personal.spaceId) {
-        throw new ApplicationError(
-          ApplicationErrorCode.VALIDATION,
-          'Personal capture target must be the active personal space'
-        );
-      }
       const result = await this.personal.commit({
         space_id: input.spaceId,
         personal_project_id: input.personalProjectId ?? null,
@@ -206,20 +208,6 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
       });
       return { route: 'personal', ...result };
     }
-    if (input.projectAgentId) {
-      throw new ApplicationError(
-        ApplicationErrorCode.VALIDATION,
-        'Project Agent knowledge can only be captured in the personal graph'
-      );
-    }
-    if (episode.sensitivity !== 'normal') {
-      throw new ApplicationError(
-        ApplicationErrorCode.VALIDATION,
-        'Private or restricted knowledge cannot enter a team-shared project queue. Use targetKind "personal" with personalProjectId to keep it in the personal graph'
-      );
-    }
-    assertPublicKnowledgeEligible(episode);
-    const workspace = this.#workspace(input.providerUrl);
     const draft = await this.personal.createPublicationDraft({
       personal_space_id: this.config.personal.spaceId,
       target_project_id: input.spaceId,
@@ -257,19 +245,33 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     projectAgentId = null,
     projectPath = null,
     taskPrompt = null,
+    sourceApplication = 'other',
+    sourceSessionId = null,
+    sessionId = null,
+    turnId = null,
+    workKind = null,
+    requiredCapabilities = [],
     limit = 100,
     agentInvocation = false,
     agentToolName = 'get_collaboration_preferences'
   } = {}) {
-    const projectResolution = await this.#resolvePreferenceProject({
-      personalProjectId,
-      projectPath
-    });
-    return getCollaborationPreferencesWorkflow(
+    const projectResolution = await this.#resolvePreferenceProject({ personalProjectId, projectPath });
+    const selection = projectPath === null && !personalProjectId && !projectAgentId
+      ? null
+      : await resolveTaskEntryAgent(
+      this, projectResolution, { projectAgentId, taskPrompt, sourceApplication,
+        sessionId: agentToolName === 'get_collaboration_preferences'
+          ? sessionId ?? sourceSessionId : turnId ? sessionId : null,
+        turnId: agentToolName === 'begin_task_context' ? turnId : null,
+        workKind, requiredCapabilities, agentInvocation, agentToolName }
+    );
+    // A rejected explicit role must not leak its private preferences via fallback.
+    const selectedAgentId = selection ? selection.agent?.agentId ?? null : projectAgentId;
+    const preferences = await getCollaborationPreferencesWorkflow(
       this,
       projectResolution,
       {
-        projectAgentId,
+        projectAgentId: selectedAgentId,
         taskPrompt,
         limit,
         agentInvocation,
@@ -277,6 +279,19 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
       },
       (items, toolName) => this.#recordAgentViews(items, toolName)
     );
+    const management = this.employees && agentInvocation &&
+      ['begin_task_context', 'get_collaboration_preferences'].includes(agentToolName)
+      ? await this.employees.taskEntry({ personalProjectId: projectResolution.personalProjectId,
+        sourceApplication, sourceSessionId, sessionId })
+      : null;
+    const managedPreferences = management ? { ...preferences, project_management_context: management } : preferences;
+    if (!selection) return managedPreferences;
+    const context = selection.agent ? await loadProjectAgentContinuity(this, {
+      projectId: projectResolution.personalProjectId, agent: selection.agent,
+      sourceApplication, taskPrompt, selectionReason: selection.reason,
+      matchBasis: selection.match_basis
+    }) : selection;
+    return { ...managedPreferences, project_agent_context: context };
   }
 
   async getUserTasteSkill({
@@ -518,7 +533,7 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
 
   async searchCurrentProjectKnowledge(input) {
     const resolution = await this.#resolvePreferenceProject({
-      personalProjectId: null,
+      personalProjectId: input.personalProjectId ?? null,
       projectPath: input.projectPath
     });
     return searchCurrentProjectKnowledgeWorkflow(this, resolution, input);
@@ -1164,7 +1179,7 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     };
   }
 
-  close() {}
+  close() { return this.employees?.close(); }
 
   async #recordAgentViews(items, toolName) {
     const unique = new Map(items.map((item) => [
@@ -1195,6 +1210,34 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     return this.#resolvePreferenceProject(input);
   }
 
+  #prepareKnowledgeCapture(input) {
+    assertNoCredentials(input);
+    const episode = providerEpisode(input);
+    if (input.targetKind === 'personal') {
+      if (input.spaceId !== this.config.personal.spaceId) {
+        throw new ApplicationError(
+          ApplicationErrorCode.VALIDATION,
+          'Personal capture target must be the active personal space'
+        );
+      }
+      return { episode };
+    }
+    if (input.projectAgentId) {
+      throw new ApplicationError(
+        ApplicationErrorCode.VALIDATION,
+        'Project Agent knowledge can only be captured in the personal graph'
+      );
+    }
+    if (episode.sensitivity !== 'normal') {
+      throw new ApplicationError(
+        ApplicationErrorCode.VALIDATION,
+        'Private or restricted knowledge cannot enter a team-shared project queue. Use targetKind "personal" with personalProjectId to keep it in the personal graph'
+      );
+    }
+    assertPublicKnowledgeEligible(episode);
+    return { episode, workspace: this.#workspace(input.providerUrl) };
+  }
+
   #workspace(providerUrl) {
     const requested = providerUrl
       ? canonicalProviderUrl(providerUrl)

package/src/graphiti/project-agent-control-plane.js

@@ -1,4 +1,8 @@
 import { agentProjectResolution } from './agent-knowledge-workflows.js';
+import {
+  getProjectAgentMemory,
+  checkpointProjectAgentMemory
+} from './project-agent-memory.js';
 import {
   authorizeExecutor as authorizeExecutorWorkflow,
   cleanupProjectAgentTestRoles as cleanupProjectAgentTestRolesWorkflow,
@@ -48,6 +52,16 @@ export const projectAgentControlPlaneHooks = Object.freeze({
 });
 
 export class ProjectAgentControlPlaneApplication {
+  async getProjectAgentMemory(input) {
+    this.#assertSpace(input.personalSpaceId);
+    return getProjectAgentMemory(this, input);
+  }
+
+  async checkpointProjectAgentMemory(input) {
+    this.#assertSpace(input.personalSpaceId);
+    return checkpointProjectAgentMemory(this, input);
+  }
+
   async upsertProjectAgent(input) {
     this.#assertSpace(input.personalSpaceId);
     return upsertProjectAgentWorkflow(this, input);
@@ -252,7 +266,10 @@ export class ProjectAgentControlPlaneApplication {
   }
 
   async getProjectAgentContext(input) {
-    const resolution = await this.#resolveProject(input.projectPath);
+    const resolution = await this.#resolveProject(
+      input.projectPath,
+      input.personalProjectId ?? null
+    );
     return getProjectAgentContextWorkflow(
       this,
       agentProjectResolution(resolution),
@@ -266,9 +283,9 @@ export class ProjectAgentControlPlaneApplication {
     );
   }
 
-  #resolveProject(projectPath) {
+  #resolveProject(projectPath, personalProjectId = null) {
     return this[projectAgentControlPlaneHooks.resolvePreferenceProject]({
-      personalProjectId: null,
+      personalProjectId,
       projectPath
     });
   }