fuli-context 0.7.6 → 0.7.7

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
     });
   }

package/src/graphiti/project-agent-mapping.js

@@ -246,6 +246,8 @@ export function providerProjectAgentTaskSubmit(input) {
     objective: input.objective,
     work_kind: input.workKind ?? input.work_kind,
     required_capabilities: input.requiredCapabilities ?? input.required_capabilities ?? [],
+    executor_capability_hints:
+      input.executorCapabilityHints ?? input.executor_capability_hints ?? [],
     duration: input.duration ?? 'ongoing',
     staffing_intent: input.staffingIntent ?? input.staffing_intent ?? 'reuse_preferred',
     lead_agent_id: input.leadAgentId ?? input.lead_agent_id ?? null,
@@ -293,6 +295,36 @@ export function projectAgentParallelPlan(value = {}) {
   };
 }
 
+export function providerProjectAgentTokenUsage(value) {
+  if (value === undefined || value === null) return value ?? null;
+  return {
+    source: value.source,
+    total_tokens: value.totalTokens ?? value.total_tokens,
+    input_tokens: value.inputTokens ?? value.input_tokens ?? null,
+    output_tokens: value.outputTokens ?? value.output_tokens ?? null,
+    cached_input_tokens: value.cachedInputTokens ?? value.cached_input_tokens ?? null,
+    cache_write_input_tokens: value.cacheWriteInputTokens ??
+      value.cache_write_input_tokens ?? null,
+    reasoning_output_tokens: value.reasoningOutputTokens ??
+      value.reasoning_output_tokens ?? null
+  };
+}
+
+export function projectAgentTokenUsage(value) {
+  if (value === undefined || value === null) return value ?? null;
+  return {
+    source: value.source,
+    totalTokens: value.total_tokens ?? value.totalTokens,
+    inputTokens: value.input_tokens ?? value.inputTokens ?? null,
+    outputTokens: value.output_tokens ?? value.outputTokens ?? null,
+    cachedInputTokens: value.cached_input_tokens ?? value.cachedInputTokens ?? null,
+    cacheWriteInputTokens: value.cache_write_input_tokens ??
+      value.cacheWriteInputTokens ?? null,
+    reasoningOutputTokens: value.reasoning_output_tokens ??
+      value.reasoningOutputTokens ?? null
+  };
+}
+
 export function providerProjectAgentTaskActivity(input) {
   const result = withoutUndefined({
     personal_space_id: input.personalSpaceId ?? input.personal_space_id,
@@ -332,6 +364,31 @@ export function providerProjectAgentTaskActivity(input) {
       worker_status: input.workerStatus ?? input.worker_status ?? null
     });
   }
+  if (hasAny(input, ['tokenUsage', 'token_usage'])) {
+    result.token_usage = providerProjectAgentTokenUsage(
+      input.tokenUsage ?? input.token_usage
+    );
+  }
+  if (hasAny(input, ['workerRuntime', 'worker_runtime'])) {
+    const runtime = input.workerRuntime ?? input.worker_runtime;
+    result.worker_runtime = runtime ? withoutUndefined({
+      application: runtime.application,
+      session_id: runtime.sessionId ?? runtime.session_id ?? null,
+      session_url: runtime.sessionUrl ?? runtime.session_url ?? null
+    }) : null;
+  }
+  copyOptional(
+    result,
+    'source_session_url',
+    input.sourceSessionUrl ?? input.source_session_url ?? null,
+    hasAny(input, ['sourceSessionUrl', 'source_session_url'])
+  );
+  copyOptional(
+    result,
+    'tools_used',
+    input.toolsUsed ?? input.tools_used ?? null,
+    hasAny(input, ['toolsUsed', 'tools_used'])
+  );
   return result;
 }
 
@@ -344,6 +401,7 @@ export function projectAgentTaskRecord(value = {}) {
     objective: value.objective,
     workKind: value.work_kind,
     requiredCapabilities: value.required_capabilities ?? [],
+    executorCapabilityHints: value.executor_capability_hints ?? [],
     duration: value.duration,
     staffingIntent: value.staffing_intent,
     status: value.status,
@@ -411,7 +469,7 @@ export function projectAgentTaskParticipantRecord(value = {}) {
 }
 
 export function projectAgentTaskEventRecord(value = {}) {
-  return {
+  const result = {
     eventId: value.event_id,
     taskId: value.task_id,
     agentId: value.agent_id ?? null,
@@ -439,6 +497,31 @@ export function projectAgentTaskEventRecord(value = {}) {
     fallbackUsed: value.fallback_used ?? false,
     createdAt: value.created_at
   };
+  copyOptional(
+    result,
+    'workerRuntime',
+    projectAgentWorkerRuntime(value.worker_runtime ?? value.workerRuntime),
+    hasAny(value, ['worker_runtime', 'workerRuntime'])
+  );
+  copyOptional(
+    result,
+    'sourceSessionUrl',
+    value.source_session_url ?? value.sourceSessionUrl ?? null,
+    hasAny(value, ['source_session_url', 'sourceSessionUrl'])
+  );
+  copyOptional(
+    result,
+    'toolsUsed',
+    value.tools_used ?? value.toolsUsed ?? null,
+    hasAny(value, ['tools_used', 'toolsUsed'])
+  );
+  copyOptional(
+    result,
+    'tokenUsage',
+    projectAgentTokenUsage(value.token_usage ?? value.tokenUsage),
+    hasAny(value, ['token_usage', 'tokenUsage'])
+  );
+  return result;
 }
 
 export function projectAgentRoutingDecisionRecord(value = {}) {
@@ -483,6 +566,7 @@ export function projectAgentTaskRouteResult(value = {}) {
     task: projectAgentTaskRecord(value.task ?? {}),
     assignedAgent: value.assigned_agent ? projectAgentRecord(value.assigned_agent) : null,
     recruitment: value.recruitment ? projectAgentRecruitmentRecord(value.recruitment) : null,
+    recruitments: (value.recruitments ?? []).map(projectAgentRecruitmentRecord),
     decision: value.decision,
     mustDiscloseRecruitment: value.must_disclose_recruitment ?? false,
     clientNotice: value.client_notice ?? null
@@ -505,6 +589,8 @@ export function projectAgentRecruitmentRecord(value = {}) {
     status: value.status,
     confirmationMode: value.confirmation_mode,
     proposedAgentId: value.proposed_agent_id,
+    participantRole: value.participant_role ?? 'lead',
+    recruitmentSlot: value.recruitment_slot ?? 'lead',
     proposedProfile: value.proposed_profile
       ? projectAgentProfileRecord(value.proposed_profile) : null,
     triggerSourceApplication: value.trigger_source_application ?? null,
@@ -542,10 +628,10 @@ export function projectAgentExecutionSummary(value) {
   if (!Array.isArray(value)) return [];
   return value.map((entry = {}) => {
     const actualExecutor = entry.actual_executor_id ?? entry.actual_executor ??
-      entry.actualExecutor ?? entry.executor_id ?? entry.executor ?? null;
+      entry.actualExecutor ?? null;
     const workSummary = entry.work_summary ?? entry.workSummary ?? entry.summary ?? null;
     const status = entry.status ?? entry.worker_status ?? entry.workerStatus ?? null;
-    return {
+    const result = {
       agentId: entry.agent_id ?? entry.agentId ?? null,
       agentName: entry.agent_name ?? entry.agentName ?? null,
       occupationEmoji: entry.occupation_emoji ?? entry.occupationEmoji ?? null,
@@ -563,8 +649,48 @@ export function projectAgentExecutionSummary(value) {
       workSummary,
       summary: workSummary,
       status,
-      workerStatus: entry.worker_status ?? entry.workerStatus ?? status
+      workerStatus: entry.worker_status ?? entry.workerStatus ?? null
     };
+    copyOptional(
+      result,
+      'workerRuntime',
+      projectAgentWorkerRuntime(entry.worker_runtime ?? entry.workerRuntime),
+      hasAny(entry, ['worker_runtime', 'workerRuntime'])
+    );
+    copyOptional(
+      result,
+      'sourceSessionId',
+      entry.source_session_id ?? entry.sourceSessionId ?? null,
+      hasAny(entry, ['source_session_id', 'sourceSessionId'])
+    );
+    copyOptional(
+      result,
+      'sourceSessionUrl',
+      entry.source_session_url ?? entry.sourceSessionUrl ?? null,
+      hasAny(entry, ['source_session_url', 'sourceSessionUrl'])
+    );
+    copyOptional(
+      result,
+      'toolsUsed',
+      entry.tools_used ?? entry.toolsUsed ?? null,
+      hasAny(entry, ['tools_used', 'toolsUsed'])
+    );
+    copyOptional(
+      result,
+      'tokenUsage',
+      projectAgentTokenUsage(entry.token_usage ?? entry.tokenUsage),
+      hasAny(entry, ['token_usage', 'tokenUsage'])
+    );
+    return result;
+  });
+}
+
+export function projectAgentWorkerRuntime(value) {
+  if (!value || typeof value !== 'object') return null;
+  return withoutUndefined({
+    application: value.application,
+    sessionId: value.session_id ?? value.sessionId ?? null,
+    sessionUrl: value.session_url ?? value.sessionUrl ?? null
   });
 }
 
@@ -587,12 +713,30 @@ export function projectAgentActivityRecord(value = {}) {
         summary: task.summary,
         occurredAt: task.occurred_at,
         sourceApplication: task.source_application ?? null,
+        sourceSessionId: task.source_session_id ?? null,
+        sourceSessionUrl: task.source_session_url ?? task.sourceSessionUrl ?? null,
+        toolsUsed: task.tools_used ?? task.toolsUsed ?? null,
         actualExecutor: task.actual_executor_id ?? task.actual_executor ?? null,
+        selectedExecutorId: task.selected_executor_id ?? null,
+        executorRuleId: task.executor_rule_id ?? task.rule_id ?? null,
         matchedExecutorRuleId: task.matched_executor_rule_id ?? task.routing_rule_id ?? null,
         executorSelectionReason: task.executor_selection_reason ?? null,
+        executorFallbackReason: task.executor_fallback_reason ?? null,
+        executorFallbackOutcome: task.executor_fallback_outcome ?? null,
+        executorBlockedReason: task.executor_blocked_reason ?? null,
+        executorDecision: task.executor_decision ?? null,
         auditId: task.audit_id ?? null,
         actualModelProvider: task.actual_model_provider ?? null,
         actualModel: task.actual_model ?? null,
+        workerId: task.worker_id ?? task.workerId ?? null,
+        workerLabel: task.worker_label ?? task.workerLabel ?? null,
+        workerOccupationEmoji: task.worker_occupation_emoji ??
+          task.workerOccupationEmoji ?? null,
+        workerStatus: task.worker_status ?? task.workerStatus ?? null,
+        tokenUsage: projectAgentTokenUsage(task.token_usage ?? task.tokenUsage),
+        ...(hasAny(task, ['worker_runtime', 'workerRuntime']) ? {
+          workerRuntime: projectAgentWorkerRuntime(task.worker_runtime ?? task.workerRuntime)
+        } : {}),
         executionSummary: projectAgentExecutionSummary(
           task.execution_summary ?? task.executionSummary
         ),
@@ -608,7 +752,12 @@ export function projectAgentRecruitmentPolicyRecord(value = {}) {
   return {
     personalSpaceId: value.personal_space_id,
     confirmationMode: value.confirmation_mode ?? 'automatic',
-    updatedAt: value.updated_at ?? null
+    updatedAt: value.updated_at ?? null,
+    ...(value.policy_status ? {
+      policyStatus: value.policy_status,
+      appliesToRecruitment: value.applies_to_recruitment,
+      warning: value.warning
+    } : {})
   };
 }
 
@@ -991,6 +1140,7 @@ export function routingLearningRecord(value = {}) {
     ratingCount: value.rating_count,
     averageRating: value.average_rating,
     neutralDueToInsufficientEvidence: value.neutral_due_to_insufficient_evidence,
+    validationWarnings: value.validation_warnings,
     weightedSuccess: value.weighted_success,
     weightedFailure: value.weighted_failure,
     evidenceRefs: value.evidence_refs,

package/src/graphiti/project-agent-memory.js

@@ -0,0 +1,115 @@
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+import { detectSensitiveContent } from '../security/sensitive-content.js';
+
+export function agentMemoryRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    !Number.isInteger(value.revision) || value.revision < 1 ||
+    !value.memory || typeof value.memory !== 'object' || Array.isArray(value.memory) ||
+    typeof value.memory.summary !== 'string') {
+    throw invalidAgentMemoryResponse();
+  }
+  return {
+    checkpointId: value.checkpoint_id,
+    personalSpaceId: value.personal_space_id,
+    personalProjectId: value.personal_project_id,
+    agentId: value.agent_id,
+    revision: value.revision,
+    memory: {
+      summary: value.memory.summary,
+      decisions: memoryNotes(value.memory.decisions),
+      openThreads: memoryNotes(value.memory.open_threads),
+      nextActions: memoryNotes(value.memory.next_actions)
+    },
+    sourceApplication: value.source_application,
+    sourceSessionId: value.source_session_id ?? null,
+    taskId: value.task_id ?? null,
+    createdAt: value.created_at
+  };
+}
+
+export function agentMemoryView(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    !Number.isInteger(value.revision) || value.revision < 0 ||
+    (value.history !== undefined && value.history !== null && !Array.isArray(value.history))) {
+    throw invalidAgentMemoryResponse();
+  }
+  const current = value.current === undefined || value.current === null
+    ? null : agentMemoryRecord(value.current);
+  const history = (value.history ?? []).map(agentMemoryRecord)
+    .filter(record => record.revision !== current?.revision);
+  return {
+    personalSpaceId: value.personal_space_id,
+    personalProjectId: value.personal_project_id,
+    agentId: value.agent_id,
+    scope: value.scope,
+    storage: value.storage,
+    authority: value.authority,
+    revision: value.revision ?? 0,
+    current,
+    history
+  };
+}
+
+export async function getProjectAgentMemory(application, input) {
+  await requireAgentMemoryAccess(application, input);
+  return agentMemoryView(await application.personal.getProjectAgentMemory(input));
+}
+
+export async function checkpointProjectAgentMemory(application, input) {
+  const prepared = await prepareProjectAgentMemory(application, input);
+  if (prepared.status === 'capture_disabled') return prepared;
+  const value = await application.personal.writeProjectAgentMemory(prepared.request);
+  return { status: 'checkpointed', ...agentMemoryRecord(value) };
+}
+
+// Validate and normalize through the same boundary without performing a write.
+// Task checkpoints send this payload to the Provider's atomic prepare operation.
+export async function prepareProjectAgentMemory(application, input) {
+  if (detectSensitiveContent(JSON.stringify(input.memory)).restricted) {
+    throw new ApplicationError(ApplicationErrorCode.VALIDATION, 'Agent working memory contains credentials');
+  }
+  await requireAgentMemoryAccess(application, input);
+  const policy = application.getCapturePolicy?.() ?? { enabled: true };
+  if (!policy.enabled) return { status: 'capture_disabled', capturePolicy: policy };
+  return { request: {
+    personal_space_id: input.personalSpaceId,
+    personal_project_id: input.personalProjectId,
+    agent_id: input.agentId,
+    expected_revision: input.expectedRevision,
+    idempotency_key: input.idempotencyKey,
+    memory: {
+      summary: input.memory.summary,
+      decisions: input.memory.decisions ?? [],
+      open_threads: input.memory.openThreads ?? [],
+      next_actions: input.memory.nextActions ?? []
+    },
+    source_application: input.sourceApplication ?? 'other',
+    source_session_id: input.sourceSessionId ?? null,
+    task_id: input.taskId ?? null
+  } };
+}
+
+async function requireAgentMemoryAccess(application, input) {
+  const agent = await application.getProjectAgent(input);
+  if (agent.profile.status !== 'active' || agent.memoryScope !== 'reviewed_agent') {
+    throw new ApplicationError(ApplicationErrorCode.VALIDATION, 'An active durable Agent assignment is required for working memory');
+  }
+  if (!(agent.profile.allowedClients ?? []).includes(input.sourceApplication ?? 'other')) {
+    throw new ApplicationError(ApplicationErrorCode.VALIDATION, 'This client is not allowed to load the Agent memory');
+  }
+}
+
+function memoryNotes(value) {
+  const notes = value ?? [];
+  if (!Array.isArray(notes) || notes.some(note => typeof note !== 'string')) {
+    throw invalidAgentMemoryResponse();
+  }
+  return [...notes];
+}
+
+function invalidAgentMemoryResponse() {
+  return new ApplicationError(
+    ApplicationErrorCode.VALIDATION,
+    'Provider returned an invalid Agent memory record'
+  );
+}